Writing flexible document outputs with YAML and Markdown syntax

ANU BDSI
workshop Reproducible research with Quarto

Emi Tanaka

Biological Data Science Institute

12th April 2024

Welcome đź‘‹

Teaching team

  • Academic statistician passionate about data science and open source software
  • Currently, Deputy Director of ANU Biological Data Science Institute and Executive Editor of R Journal
  • PhD in Statistical Bioinformatics
  • BSci (Adv Maths) with major in Mathematics and Statistics
  • Loves data and coding

        https://emitanaka.org     @statsgen     fosstodon.org/@emitanaka

  • 2nd year of PhD student at ANU, working on phylogenomics methods to study hybridisation
  • BSci in Bioinformatics
  • Enjoy hiking and science
  • jeremiasivan
  • (Almost finishing) PhD student @Moritz Lab, E&E Division, RSB, ANU
  • Working on historical biogeography of Indo-Australian birds
  • BSc (Hons) with major in Zoology and Ecology & Conservation
  • Loves games, art markets, and FOOD
  • @goaudreymp
  • https://linktr.ee/goaudreymp
  • 3rd Year PhD student @ Linde Lab, E&E Division, RSB, ANU
  • Investigating the evolution of the Australian orchid flora and associated funga
  • MScSt (Biodiversity Science)
  • Loves playing music, reading, nature
  • @rpodonnell
  • rpodonnell.github.io
  • 2nd Year PhD student @ Sequeira Lab, E&E Division, RSB, ANU
  • Identifying social, collective, or coordinated movement behaviour patterns in sharks using tracking data
  • MSc (Marine Biology), BSc (Biology)
  • Loves triathlon, hiking and the ocean
  • @nilskreuter
  • https://linktr.ee/nilskreuter

Workshop materials

All materials will be hosted at
https://anu-bdsi.github.io/workshop-intro-quarto/

đź•™ Schedule

Time Content
10:00–10:45 Writing flexible document outputs with YAML and Markdown syntax
10:45–11:30 Dynamic documents with code
11:30–11:40 Break
11:40–12:25 Towards better reproducible practice
12:25–13:00 Writing

Today’s learning objectives

  • Generate HTML, PDF, or Word documents using Markdown syntax
  • Understand the anatomy of Quarto documents
  • Develop dynamic documents containing code (in R, Python, or Julia) using Quarto
  • Implement various code chunk options to customize chunk behaviour
  • Recognize the significance of reproducibility and grasp the concept of literate programming
  • Apply reproducible practices
  • Establish an organized folder structure for data projects

Current learning objective

  • Generate HTML, PDF, or Word documents using Markdown syntax
  • Understand the anatomy of Quarto documents
  • -Develop dynamic documents containing code (in R, Python, or Julia) using Quarto
  • -Implement various code chunk options to customize chunk behaviour
  • -Recognize the significance of reproducibility and grasp the concept of literate programming
  • -Apply reproducible practices
  • -Establish an organized folder structure for data projects

Quarto in a nutshell

  • Quarto integrates text + code in one source document with ability to render to many output formats (via Pandoc).
  • Quarto is the next generation of R Markdown.

R Markdown

  • Quarto and R Markdown are very similar.
  • The same team that created R Markdown created Quarto.
  • Quarto supersedes R Markdown so we focus on Quarto.

R Markdown

Quarto

What can you do with Quarto?


These HTML slides are made using Quarto.

What can you do with Quarto?



These dynamic reports are made using Quarto.

Template available at
https://github.com/anuopensci/quarto-anu-report

What can you do with R Markdown?

This thesis (online and pdf) is made using R Markdown (previous generation of Quarto).
Available at https://thesis.earo.me/

What can you do with Quarto?

Possibilities are endless…

  • Microsoft Word document (.doc, .docx)
  • Open Document Text (.odt)
  • Rich text format (.rtf)
  • e-book format (.epub)
  • Markdown documents (.md)
  • Dashboard (.html)
  • Books (.pdf or .html)
  • Websites (collection of web pages)

Starting your own project

  • RStudio Desktop > New Project > New Directory > New Project
  • For those without RStudio Desktop, create a new directory.

🔍 Open and inspect the file example-01-first-quarto.qmd

Quarto basics

  • If you are not using RStudio Desktop, open with your own editor.

Render to a HTML document

  • If you are not using RStudio Desktop, open the terminal and run
quarto render /your/file/location/filename.qmd

Render to a PDF document

  • If you are not using RStudio Desktop, open the terminal and run
quarto render /your/file/location/filename.qmd

RStudio Desktop

How does it all work?

Quarto via knitr/jupyter: qmd md

Pandoc: md html, pdf, docx

Meta data with YAML

YAML - YAML Ain’t Markup Language

Basic format

---
key: value
---

Example

---
title: "Reproducible Research with Quarto"
subtitle: "The Basics"
author: "Emi Tanaka"
date: "`r Sys.Date()`"
engine: knitr
format: html
---
  • There must be a space after “:”!
  • White spaces indicate structure in YAML - don’t use tabs though!
  • Same as R, you can comment lines by starting with #.
  • YAML is case sensitive.

YAML with multiple key values

  • A key can hold multiple values.

  • Multiple values can be listed as a list:

key: 
  - value1
  - value2
  - value3
  • Or it can be separated by a comma within a square bracket:
key: [value1, value2]

Values spanning multiple lines

---
title: >
  this is a  
  
  **single line**
  
abstract: |
  | this value spans   
  | *many lines* and      
  | 
  | appears as it is     
  
format: html
---

🔍 Open and inspect the file example-02-yaml.qmd

A key can contain keys

---
format: 
  html:
    toc: true
    theme: sketchy
---
  • What does each of the above keys do?

Text via Markdown

Headers

# Header 1
## Header 2
### Header 3
#### Header 4
##### Header 5
###### Header 6

Lists


Ordered list

1. Item 1
2. Item 2
   - Subitem 3A
   - Subitem 3B
  
Unordered list

* Item 1 
  * Subitem 1
* Item 2
- Item 3
- Item 4

Formatting text

 **This text is bold** 
 
 __This text is also bold__  
 
 *This text is italic* 
 
 _This text is also italic_  
 
 **_You can combine both_**

🔍 Open and inspect the file example-03-markdown.qmd

Summary

  • Use YAML to control document’s meta data.
  • Use Markdown syntax in the body of the document to write content.
  • Focus on writing the content instead of formatting!
  • The best guide for Quarto is at https://quarto.org/docs/guide/.

Quarto cheatsheet

anu-bdsi.github.io/workshop-intro-quarto/