Create Quarto dashboards with Python
Learn how to create Quarto dashboards with Python! Senior Product Marketing Manager Isabella Velásquez walks through building a Quarto dashboard from scratch, using water insecurity data from the TidyTuesday project. You'll learn how to structure a Quarto document, preview dashboards, and customize layouts and themes. See Isabella's code here: https://github.com/ivelasq/water-insecurity-dashboard And the dashboard here: https://ivelasq-water-insecurity-dashboard.share.connect.posit.cloud/ Resources: Quarto dashboards guide: https://quarto.org/docs/dashboards/ Posit Connect Cloud: connect.posit.cloud Hello, Dashboards!: https://www.youtube.com/watch?v=HW7QbqI4fH0&t=590s TidyTuesday project: https://github.com/rfordatascience/tidytuesday Posit PydyTuesday GitHub repo: https://github.com/posit-dev/python-tidytuesday Other videos in this PydyTuesday playlist: https://www.youtube.com/playlist?list=PL9HYL-VRX0oSDQjicFMLIIdcLv5NuvDp9 #pythoncontent
image: thumbnail.jpg
Transcript#
This transcript was generated automatically and may contain errors.
Hi everyone, my name is Isabelle Velazquez. Today we're going to be talking about how to create a Quarto dashboard with Python code. Quarto is an open source scientific and technical publishing system. It allows you to create a variety of documents, such as reports, websites, and presentations, using code and text. And as of Quarto 1.5, you can also create dashboards.
Quarto dashboards are an easy way of creating interactive displays of data, text, tables, and plots that you can share with others.
The data that we're going to be looking at today is water and security data from 2023. This is data from the TidyTuesday project. TidyTuesday is a weekly project where datasets are released and everyone in the data science community is invited to play around with it, visualize it, and create something engaging or inspiring.
Setting up the environment
So I will be using Positron as my IDE, but most of this experience will be somewhat similar if you use VS Code or another editor. One difference is that Quarto comes bundled with Positron, so we do not have to install it separately. But if you haven't configured Quarto in your editor, we have some resources to get started in the description. Assuming you have Quarto installed, we can proceed with creating our dashboard.
In Positron, I hit Command-Shift-P to open up the command palette, then type Quarto new document, or navigate to it, to create a new Quarto document in a QMD file. This is the file in which we will create our dashboard. I'm going to title my document Water and Security in the United States Western States 2023.
Building the document structure
I'm going to paste each section of the document and walk through what each step is doing. In a Quarto document, we have what are called code chunks. They are denoted by three backticks and then the programming language that you want to use in curly braces. In this case, Python is in the curly braces because we're going to be running Python.
Quarto documents also allow you to include code chunk options. These are instructions for how you would like to customize your code chunks in your render document. Include false is an example of a code chunk option. I want this code chunk to run, but not to show up in my render document.
Within the script, you can put executable code. I have the script.py file that has all the document setup, such as importing the modules, reading the data, and cleaning it up. Rather than have everything within my QMD file and making it super long, I have it split out so all the data cleaning steps are in the script, and then the QMD file can solely include what I need for my dashboard.
You do not have to do it this way. For example, you could instead read your CSV and clean it up in a code chunk in the QMD file. This is just how I decided to set up my project. Again, it's completely up to you.
To actually execute the code, you can click run cell here, and everything within the code chunk will be run. In Positron, I can also preview my data, look at some histograms to see its distributions very quickly, or just take a look at what are contained within the cells.
Now I add another code chunk with more executable code. So I have this object called wi-west-2023-gt. I'm using the great tables package, create a table, call that object at the end of the code chunk, and if I click run cell here, then I can see a preview of what this table will look like in Positron's viewer pane.
This table shows the counties facing the most water insecurity and the percent lacking plumbing in that county. I'm going to include this table in my dashboard.
Next, I'm going to create another code chunk. This one creates a box plot using that water insecurity data for the western states in 2023. I click run cell, and I can see a preview of what the plot will look like in Positron's plot viewer.
In addition to viewing the plot directly in my IDE, I could also do things like save it, copy the plot to the clipboard, and zoom in if I really wanted to look at it closely. But let's say I'm good with this plot, so we can continue with our dashboard.
Converting to a dashboard
So just to recap, I have a code chunk that's reading my data, cleaning it up in a separate script.py file. Next, I have two code chunks for a table and a box plot using that data. So great!
If I scroll up here, I have format HTML, which is one of the formats that you can create with Quarto. If I render this, it's going to produce an HTML page that I could, say, put in a website. If I want to see what my document looks like right now, first I save the document, call it index.qmd. Then I can click this preview button up here.
Let's say I want to see what this looks like in the browser. I can pop it out and take a look. I have the title up here, the first code chunk with the GT table, and it's showing both the code and the output because I haven't specified any code chunk options in the document, saying that I don't want to see the code. And then similarly, the second code chunk for the plot as well.
We're well on our way, but now let's say I would like to convert this to a dashboard. I return to my QMD file and specify format dashboard instead of format HTML. And that's it. This will change my Quarto output from HTML to a dashboard. I can hit preview again.
And the great thing about Quarto is all of these different file types are native. Whether you're creating an HTML file, dashboard, presentation, you don't have to install anything separately. Everything is bundled within Quarto itself.
And the great thing about Quarto is all of these different file types are native. Whether you're creating an HTML file, dashboard, presentation, you don't have to install anything separately. Everything is bundled within Quarto itself.
I pop out the rendered dashboard and I can see its first iteration. By default, Quarto dashboards are laid out first by row and by column. So each separate component, whether it be text or table or plots, will be put in a cell within the dashboard. So here I have my title and then my two code chunks as separate components, one being the great tables table and the other being the box plot.
Notice that the code isn't showing up in the dashboard. That's because the dashboard format assumes you don't want to show code and just want to display the output.
Configuring the layout
But this dashboard is a little hard to read. Say instead I want for a single row to contain both the table and the plot. So I can go back and start configuring the layout using this idea of either rows or columns. I want the table to be its own column and I want the plot to be its own column in a single row. I can configure the layout using headings. Different levels of headings will define the layout of the dashboard.
So here I'm saying in this row I want two separate columns. Since it's columns within the same row, I don't need to explicitly define them, but I'll show you what that looks like in a bit. The Quarto dashboard will know that these should be in a single row because they're under the same heading. I have my dashboard with a row with two columns, one of the columns being the table and the other being the plot.
Here I can keep configuring the dashboard to look exactly the way I want. So say this table, I want it to take up a little less space than 50%. Here I'm going to explicitly put the table in its own column. And then in curly braces, I can say this column should take up 30% of the space. Then again, explicitly listing out the other column, say that this one should take up 70%.
I can save and then hit preview. When I pop it out, I can see this one here is a bit more narrow. This one's a bit wider.
Theming and publishing
Quarto also has extensive theming capabilities. There are over 20 built-in bootstrap themes that you could add. So for example, I go back to my QMD file. Then I specify format, dashboard, theme, and I'm going to pick sandstone. Hit preview again, and now the sandstone theme has been applied.
You can also customize Quarto dashboards with your custom theme or use the new brand.yaml capability. Brand.yaml allows you to customize Quarto using a YAML file. And it's easy to put the same YAML file in different projects if you have something that you would like to say adhere to a corporate style guide or something like that.
So this was a very brief overview of how to create Quarto dashboards with Python. Here I can publish to PositConnect Cloud so I can share with my organization and colleagues. And with that, please let us know what you would like to see next.
