QTM 350 - Data Science Computing

Lecture 09 - More Quarto

Danilo Freire
danilo.freire@emory.edu

Emory University

30 September, 2024

Nice to see you all again! 😊

Brief recap 📚

Quarto and literate programming

  • Literate programming is a paradigm introduced by Donald Knuth in 1984
  • The main idea is to treat code as a narrative, where code and documentation are interwoven
  • Quarto allows us to easily write documents that mix code and text
  • It supports multiple programming languages, and can be used to create reports, slides, and websites
  • Quarto is very similar to R Markdown
  • All documents have three main components:
    • YAML header with metadata
    • Markdown content (text)
    • Code chunks
---
title: My Quarto Document
subtitle: A simple example
author: Danilo Freire
date: 2024-09-30
format: html
editor:
  render-on-save: true
---

# Introduction

This is a simple Quarto document.

```{python}
print("Hello, world!")
```

## Subsection

[Link](https://www.emory.edu).

A little more on Markdown

  • Headings: #, ##, ###, etc.
  • Emphasis: *italic*, **bold**, ~~strikethrough~~
  • Lists: *, 1., -
  • Links: [text](url)
  • Images: ![alt text](url)
  • Code: `code`, ```code```
  • Tables:
| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |
  • Blockquotes: > quote
  • Horizontal rules: ---
  • Line breaks:
  • Footnotes: [^1]
  • Superscript: 2^10^
  • Subscript: H~2~O
  • Math: $\LaTeX$
  • For equations, use $ or $$
  • Check the LaTeX Wiki for math symbols
  • More at Markdown Guide

Example

# Heading 1

This is a paragraph[^1].

## Heading 2

This is *italic*, this is `code`, 
this is ~~strikethrough~~.

This is a [link](https://www.emory.edu).
Equation: $\mu = \frac{1}{n} \sum_{i=1}^{n} x_i$

List:

- Item 1
- Item 2
  - Subitem 1

[^1]: This is a footnote.

| Header 1 | Header 2 | Header 3 |
|:---------|:--------:|---------:|
| Cell 1   | Cell 2   | Cell 3   |

Heading 1

This is a paragraph1.

Heading 2

This is italic, this is code, this is strikethrough.

This is a link. Equation: \(\mu = \frac{1}{n} \sum_{i=1}^{n} x_i\)

List:

  • Item 1
  • Item 2
    • Subitem 1
Header 1 Header 2 Header 3
Cell 1 Cell 2 Cell 3

Quarto formats 🛠️

Jupyter notebooks

  • You just have to add a YAML header to your notebook
  • Quarto will convert it to html, pdf, or other formats
  • quarto render notebook.ipynb --to html will convert a notebook to html
  • You can add --execute to run the code
  • Benefits:
    • Easy to host
    • Easy to convert
    • More formatting options

PDFs

  • Most articles and reports are in PDF format
  • You will need a LaTeX distribution to create PDFs
  • You can install it with quarto:
    • quarto install tinytex
  • If you use R, you can use tinytex with:
    • install.packages("tinytex")
    • tinytex::install_tinytex()
  • This is strongly recommended as a LaTeX distribution is huge and takes a long time to install
  • More information here

PDFs from Jupyter notebooks

  • You can convert Jupyter notebooks to PDFs using tinytex and quarto
  • Add --to pdf to the command and --execute to run the code
  • quarto render notebook.ipynb --to pdf --execute
  • It is the same as using the .qmd format (which is preferred), but it works with your existing notebooks

Adding references

  • You can add academic references to your documents using bibtex
  • BibTeX is a reference management software developed for LaTeX
  • A bibtex file is a plain text file with .bib extension
  • You can add references to your YAML header
  • Use @key to cite a reference, [@key] to cite in parentheses
  • The key is the first line of the reference in the .bib file (e.g., @article{nash1950equilibrium,)
  • More information here
  • The easiest way to manage references is with a reference manager like Zotero or download a BibTex reference from Google Scholar
  • Just search for a paper and click on the cite button
  • Then click on BibTeX and copy the reference to your .bib file

Example

@article{nash1950equilibrium,
  title={Equilibrium points in n-person games},
  author={Nash Jr, John F},
  journal={Proceedings of the national academy of sciences},
  volume={36},
  number={1},
  pages={48--49},
  year={1950},
  publisher={National Acad Sciences}
}
  • Save it on your references.bib file (or any other name)
  • Quarto will automatically format the references
  • More information about BibTeX here

Example

Then you add the references to your YAML header:

---
title: "Matplotlib Demo"
author: "Norah Jones"
date: "2024-09-30"
date-format: "MMMM D, YYYY"
format: 
  pdf:
    fig-width: 3
    fig-height: 2
    margins: 2in
bibliography: references.bib
---

Formatting LaTeX documents

  • LaTeX allows you to format your documents in a very detailed way
  • As we discussed in the previous lecture, LaTeX is not very user-friendly
  • But you can use available templates to make your life easier
  • I have some of my own templates here: https://github.com/danilofreire/quarto-templates
  • You can save some time by using them, or finding others you like 😅
format: 
  pdf:
    template: your-template.latex

Try it yourself! 🚀

  • Create a new Quarto document (.qmd) in VS Code
  • Add a heading and some text (headings, lists, links and a table)
  • Add a Python code chunk with a simple graph and a print statement
    • Change the chunk options to echo: true and eval: true
    • Add a fig.cap option to the chunk
    • Add a caption to the figure
    • Add a label to the figure and reference it in the text
  • Add a BibTeX reference to your document and render it both to HTML and PDF
  • Use the quarto command to render the document
  • Example

Presentations!

Slides and reveal.js

  • You can also create slides with Quarto! 🎉
  • Quarto has several advantages:
    • Over R Markdown: more flexibility, more languages, Revealjs support
    • Over PowerPoint: plain text, easier to share, easier to host, version control
    • Over Google Slides: version control, offline access, more flexibility
    • Over Beamer: Oh my God, so much easier! 😅

How to create slides

  • Create a new Quarto document with format: revealjs
  • Add a YAML header with the metadata, as usual
  • Add your content in Markdown
  • # creates a new section, ## a new slide
  • Quarto uses ::: to create and end a new “element” in the slides. For instance, to create columns, change font size, centre text, etc.
    • If you know html, this is the same as creating div elements (e.g., <div class="columns"> </div>)
  • You can add code chunks, images, tables, and references
  • To render the slides, use the quarto command:
    • quarto render slides.qmd --to slides

Example

Simple slides

Where to host slides

  • There are two easy ways to host a presentation:
    • GitHub: you can create a repository and upload the files
    • Githack: you can upload the files and get a link to share
  • GitHack is the easiest: you just paste the link to the .html file in your repository and it will create a link for you
  • On GitHub, you have to publish the repository and go to the settings to enable GitHub Pages (more on this later)

Websites

  • Finally, you can also create websites with Quarto! 😎
  • Quarto websites are static, which means they are very fast (although a bit limited in functionality)
  • They are great for blogs, documentation, portfolios, and other simple websites
  • You can also host them for free on GitHub, Netlify, or Vercel
  • More information here

Website structure

  • Quarto compiles the .qmd files into separate .html files (pages)
  • Quarto websites are highly customisable, and you can create your own themes if you know CSS
  • You can add a navigation bar, a footer, a sidebar, and other elements
  • Websites have the same structure:
    • _quarto.yml: metadata that organises the website
    • *.qmd: content files, which will be displayed as pages
    • index.qmd: the home page
    • styles.css: custom CSS for the website
  • Let’s see how they work together in the example website 😊

Create project in VS Code

  • To create a website in VS Code, execute the Quarto: Create Project command from the command-palette
  • Press Ctrl+Shift+P and type Quarto: Create Project

Select website format

  • Now, you need to select the website format

Select a directory

  • Choose a directory for your project
  • It is a good idea to create a new folder for your website

Project created!

  • Your project is now created! 🎉
  • You can see the structure of the website in the sidebar
  • Click on Preview button to see the website (first button on the right)
  • You can add new pages, change the theme, and customise the website as you like
  • Let’s see how to do that!

Configuration file: _quarto.yml

  • The _quarto.yml file contains the metadata for the website
  • In this file, you will see the project type, the website title, the pages that will be included, the theme, and other options
  • The list of themes is available here
  • For our newly created project, the file looks like this:
project:
  type: website

website:
  title: "today"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd

format:
  html:
    theme: cosmo
    css: styles.css
    toc: true

The .qmd files

  • The .qmd files are the content of your website
  • They follow the same format as the other Quarto documents, with a YAML header and Markdown content
  • In this case, the YAML header contains (usually) only the title of the page
  • The content can be as simple or as complex as you like, as long as it is static and in Markdown
---
title: "About"
---

# About

This is a simple website created with Quarto.

Our website

  • Let’s see the _quarto.yml file for our course website
  • The file is available here
project:
  type: website
  output-dir: docs

website:
  title: "QTM 350"
  page-navigation: true
  back-to-top-navigation: true
  reader-mode: true
  repo-url: https://github.com/danilofreire/qtm350
  repo-actions: [issue, source]
  repo-branch: gh-pages
  navbar:
    pinned: true
    tools:
      - icon: github
        href: https://github.com/danilofreire/qtm350
    left:
      - href: syllabus.qmd
        text: Syllabus
      - href: lectures/lectures.qmd
        text: Lectures
      - href: tutorials/tutorials.qmd
        text: Tutorials
      - href: assignments/assignments.qmd
        text: Assignments
      - href: LICENSE.html
        text: " "
  page-footer: 
    left: "Copyright 2024, Danilo Freire. The content of this site is licensed under the [MIT License](LICENSE.qmd)." 
    right: 
      - icon: github
        href: https://github.com/danilofreire/qtm350

format:
  html:
    theme: 
      light: lumen
      dark: solar
    css: styles.css
    toc: true

The index.qmd file

  • The index.qmd file is the home page of your website
  • This is a special file that will be displayed when you access the root of your website
  • While all other .qmd files are optional, this one is required
  • The index.qmd for our course website is very simple:
---
title: "QTM 350 - Data Science Computing"
---

Welcome to [QTM 350](https://github.com/danilofreire/qtm350)! [...]

We will meet every Monday and Wednesday [...]

## Contact Information

- **Name**: [Danilo Freire](https://danilofreire.github.io/)
- **Email**: [`danilo.freire@emory.edu`](mailto:danilo.freire@emory.edu)
- **Office Hours**: By appointment at your convenience, please email me to schedule a meeting

[...]
  • The full file is available here

How to publish a website

  • To publish a website on GitHub, you need to create a repository with your website files
  • The repository will be hosted on GitHub Pages, which is a free service
  • Each repository can have a website, and you can choose the branch where the website files are stored
  • For our course website, the files are stored in a docs folder in the gh-pages branch
  • This is because I did not want to mix the website files with the course files
  • You can create your website with quarto preview (run inside the project folder)
  • Or with quarto render (to render the website to the output directory)
  • In my case, I use quarto render docs/
  • Then you just add, commit, and push the files to your repository! 😊
  • To create a repository with GitHub Pages:
    • Create a new repository on GitHub
    • Go to the repository settings
    • Scroll down to the GitHub Pages section
    • Choose the branch where the website files are stored
    • Choose the folder where the website files are stored
    • Click on Save
    • You will get a link to your website 🎉

On GitHub 🐙

And voi-là! 🎉

And now you know everything Quarto can do! 😎

That’s all for today! 🎉

See you next time! 😊

Appendix 01

---
title: "My Quarto Document"
subtitle: "A simple example"
author: "Danilo Freire"
date: "2024-09-30"
format: html
bibliography: references.bib
---

# Introduction

This is a simple Quarto document. This is @fig-sine.

```{python}
#| echo: true
#| eval: true
#| fig-cap: "Sine function"
#| label: fig-sine 

import matplotlib.pyplot as plt
import numpy as np

x = np.linspace(0, 10, 100)
y = np.sin(x)

plt.plot(x, y)
plt.xlabel("x")
plt.ylabel("sin(x)")
plt.title("Figure 01")
plt.show()

Back to main text

More Quarto