14  Using Quarto

14.1 Introduction

A significant part of your role as a data analyst involves communicating results to others through reports. Quarto is one of the most powerful and versatile tools for producing such reports. It enables you to generate dynamic documents by combining formatted text and results produced by code. With Quarto, you can create documents in various formats such as HTML, PDF, Word, PowerPoint slides, web dashboards, and many others.

Most of our documents in the GRAPH courses are actually written in Quarto!

In this lesson, we will cover the basics of this powerful tool.

Note that for this lesson, the video may be easier to understand than the lesson notes, since there are many graphical user interface steps that are hard to describe in writing.

14.2 Learning Objectives

By the end of this lesson, you should be able to:

  • Create and render a Quarto document that includes Python code and narrative text.
  • Output documents in multiple formats, including HTML, PDF, Word, etc.
  • Understand basic Markdown syntax.
  • Use code chunk options to control code execution and output display.
  • Use Python packages to display tables and figures in Quarto documents.

14.3 Installing Quarto

To get started, you first need to install Quarto.

Search for “quarto download” in your favorite search engine. Follow the results to the “Quarto.org” website, and then follow the instructions for your operating system. (We are not providing a direct link here since the exact link may change over time).

After installing, you can check that it is installed by running the following command in the command line or terminal:

quarto --version

Now that Quarto is installed, use it to install the tinytex package, which we will need to compile our PDFs:

quarto install tinytex

To use all the features of Quarto in VSCode, we need to install the Quarto extension and the Jupyter extension. You can install these in the Extensions tab of VSCode. Be sure to install the official versions of these extensions; they should have checkmarks next to them.

That’s a lot of installations, but fear not—you only have to do these steps once on your computer.

14.4 Project Setup

To begin, open your graph_courses_python project in VSCode.

If you did not watch the previous video explaining project setup, please do so now. In that video, we explain how to create a project folder, create a virtual environment, select an interpreter, and install the jupyter, ipykernel, kaleido, itables, plotly, and pandas packages.

14.5 Create a New Document

A Quarto document is a simple text file with the .qmd extension.

To create a new Quarto document, create a new file and save it with a .qmd extension, for example, first_quarto_doc.qmd.

Add two sections to your document with the following text:

# Section 1

Hello

---

# Section 2

World

14.6 Adding Code Chunks

You can add code chunks to your document by using the following syntax with the shortcut Cmd + Shift + I (on Mac) or Ctrl + Shift + I (on Windows). Alternatively, you can click on the “…” button at the top right of the screen.

Let’s create a code chunk that adds two numbers together and displays the result:

2 + 2
4

You should see a “Run Cell” button in the toolbar. Click this to run the code chunk.

VSCode may prompt you to install the ipykernel package if you have not yet installed it in your current environment. Go ahead and install it.

Now practice adding one more code chunk at the end of the document that multiplies 3 by 3.

As you add these, you should see the buttons “Run Next Cell” and “Run Above” also appear.

There are two shortcuts you should also get used to:

  • Cmd + Enter (Mac) or Ctrl + Enter (Windows/Linux) to run the code chunk.
  • Option + Enter (Mac) or Alt + Enter (Windows/Linux) to run the current line or the highlighted section of code.

To test these, add multiple lines of code to one code chunk, then practice running the whole chunk with the first shortcut, and line by line with the second.

As you can see, we can use Quarto as an interactive document similar to a Jupyter notebook or Google Colab. But what makes it really shine is its ability to output to many formats.

Let’s see how to use this functionality.

14.7 Quarto Document Header (YAML)

At the top of the document, let’s add a YAML section. This is where we can specify details about the document, such as its title, author, and format.

---
title: "My First Quarto Document"
author: "Your Name"
format: html
---

The format is where we can specify the output format of the document. For now, we are trying to keep things simple and just use HTML.

For things to render properly, you need the jupyter package. Watch our video on setting up a virtual environment if you have not done this yet and are not sure how to install packages.

To render the document, click on the “Render” button in the top right of the screen.

You should see a new tab open in your VSCode.

If you go to the explorer, you should see a new file called first_quarto_doc.html.

So now we have the main elements of a Quarto document:

  • The YAML header
  • Section headers
  • Text
  • Code chunks
  • The outputs of those code chunks

These elements together make Quarto a very powerful tool for reporting.

You can also customize the output format with additional options. For example, to embed resources directly into the HTML file, you can modify the format section in the YAML header:

format:
  html:
    embed-resources: true

Another powerful feature of Quarto is its ability to output to many formats.

14.8 Output Formats

You can change the format value in the YAML header to experiment with other formats.

Try the following formats:

  • html: Renders the document as an HTML webpage.
  • pdf: Renders the document as a PDF. You will need to have LaTeX (or tinytex) installed on your computer to use this format.
  • docx: Renders the document as a Microsoft Word document.
  • pptx: Renders the document as a PowerPoint presentation.
  • revealjs: Renders the document as an HTML slideshow.
  • dashboard: Renders the document as an interactive dashboard.

There is a chance some of these may not work on your computer due to different operating systems or versions of software.

14.9 Markdown

The text inside Quarto documents is written in Markdown.

Markdown is a simple set of conventions for adding formatting to plain text. For example, to italicize text, you wrap it in asterisks *text here*, and to start a new header, you use the pound sign #. We will learn these in detail below.

In your editor, you can refer to the “Markdown Quick Reference” or “Cheatsheet” to learn more about Markdown syntax.

You can define titles of different levels by starting a line with one or more #:

# Level 1 Title

## Level 2 Title

### Level 3 Title

The body of the document consists of text that follows the Markdown syntax. A Markdown file is a text file that contains lightweight markup to help set heading levels or format text. For example, the following text:

This is text with *italics* and **bold**.

You can define bulleted lists:

- First element
- Second element

Will generate the following formatted text:

This is text with italics and bold.

You can define bulleted lists:

  • First element
  • Second element

Note that you need spaces before and after lists, as well as keeping the listed items on separate lines. Otherwise, they will all crunch together rather than making a list.

We see that words placed between asterisks are italicized, and lines that begin with a dash are transformed into a bulleted list.

The Markdown syntax allows for other formatting, such as the ability to insert links or images. For example, the following code:

[Example Link](https://example.com)

… will give the following link:

Example Link

We can also embed images. In your document, you can type:

![Alt text](images/picture_name.jpg)

Replace “Alt text” with a description of the image (it can also be blank), “images” with the name of the image folder in your project, and “picture_name.jpg” with the name of the image you want to use. Alternatively, in some editors, you can drag and drop the image into your document.

14.10 Code Chunk Options

It is possible to pass options to each code chunk to modify its behavior.

For example, a code chunk looks like this:

# Your code here
x = 2 + 2
print(x)
4

But you can add options to control the code chunk’s execution and display:

4

In this example, the echo: false option tells Quarto not to display the code in the rendered document, only the output.

14.10.1 Global Options

You may want to apply options globally to all code chunks in your document. You can set default code execution options in the YAML header under the execute key.

For example:

---
title: "Quarto Document"
format: html
execute:
  echo: false
---

This will set echo: false for all code chunks.

14.11 Displaying Tables

By default, pandas DataFrames display neatly in Quarto. However, for interactive tables, we can use the itables package.

Ensure that you have the itables package installed. If not, you can install it using the following command:

!pip install itables

Then, you can run code similar to the following:

import plotly.express as px
from itables import show

tips = px.data.tips()
show(tips)
total_bill tip sex smoker day time size
Loading ITables v2.2.2 from the internet... (need help?)

Note that interactive tables will only work in HTML formats. We will look at tables for other formats later.

14.12 Displaying Plots

For interactive plots, the plotly package is very useful.

tips = px.data.tips()
tips_sex = px.violin(tips, x="day", y="total_bill", color="sex")
tips_sex.show()

This will display an interactive Plotly plot in the HTML output.

For static outputs like PDFs and Word documents, we need to save the plot as an image file and then include it in the document.

First, save the plot as an image:

tips_sex.write_image("tips_sex_plot.png")

This command will create a static image file in the same folder as your document. We can then include it in the document as follows:

![Violin plot of total bill by day and sex](tips_sex_plot.png)

This will display the image in the output.

14.13 Wrapping Up

In this lesson, we covered how to create and render Quarto documents, add formatting, and include code chunks. We also learned how to use code chunk options to control the behavior of our documents. We experimented with different output formats and how to customize the display of our documents.

With these tools, you can create dynamic and interactive reports that are easily shareable in various formats. Quarto’s flexibility and integration with Python make it an excellent choice for data analysts and researchers alike.