Quarto Dashboards 1: Hello, Dashboards! | Mine Çetinkaya-Rundel | Posit
You already analyze and summarize your data in computational notebooks with R and/or Python. What’s next? You can share your insights or allow others to make their own conclusions in eye-catching dashboards and straight-forward to author, design, and deploy Quarto Dashboards, regardless of the language of your data processing, visualization, analysis, etc. With Quarto Dashboards, you can create elegant and production-ready dashboards using a variety of components, including static graphics (ggplot2, Matplotlib, Seaborn, etc.), interactive widgets (Plotly, Leaflet, Jupyter Widgets, htmlwidgets, etc.), tabular data, value boxes, text annotations, and more. Additionally, with intelligent resizing of components, your Quarto Dashboards look great on devices of all sizes. And importantly, you can author Quarto Dashboards without leaving the comfort of your “home” – in plain text markdown with any text editor (VS Code, RStudio, Neovim, etc.) or any notebook editor (JupyterLab, etc.). This video takes you through 0:00 - Overview of building dashboards with Quarto 0:15 - Dashboard basics 7:40 - First dashboard in R 10:30 - First dashboard in Python 11:43 - Live coding demo Slides can be found at https://mine.quarto.pub/quarto-dashboards/1-hello-dashboards/#/title-slide and the starter documents for the accompanying exercises at https://github.com/mine-cetinkaya-rundel/olympicdash. Materials for all parts of the videos can be accessed at https://mine.quarto.pub/quarto-dashboards
image: thumbnail.jpg
Transcript#
This transcript was generated automatically and may contain errors.
Welcome and hello to Quarto Dashboards. In this multi-part video series, we're going to build a Quarto Dashboard using data from the Olympics. So, the first part is Hello, Dashboards! Let's start briefly with what Quarto is. Quarto is a relatively new, it's been around for a few years, open-source scientific and technical publishing system. It aims to make the process of creating and collaborating dramatically better. With Quarto, you can start with a single source, and you can use many computing languages in it in your code cells. This could be R, Python, Julia, or Observable. And you can weave together your narrative text and your code to produce elegantly formatted output as documents, web pages, blog posts, books, and more. And one of those more things, since Quarto 1.4, is dashboards.
So before we get started, if you're going to be following along with any of the code, you want to make sure that you have a relatively recent version of Quarto, at least one that is beyond 1.4. If you go to your terminal and type Quarto dash dash version, this should give you the version of your Quarto installation. And if you're behind 1.4, go ahead and install the newest version of Quarto, and then you can follow along.
A tour of example dashboards
Here are some dashboards that were made with Quarto, and I'm going to scroll through a few of these before we get started building our own, and I'll highlight a few features of them. So here we have a dashboard on Customer Churn, and we can see that it actually has two pages. So the page we're seeing here, and then another page called Data. And then we can see that the content is organized in rows. So a skinny row of value boxes, another row of plots, and then a row of tables. This one is similarly organized in rows again, 1, 2, 3. And it also has multiple pages, but it has another feature that is a sidebar.
Here we can see that the content is organized in columns. So we have two columns of content, and within the first column, we've split it into rows. Again, a top row of value boxes, and then a lower row of table. And on this side, we're seeing a visualization, and that is actually an interactive visualization that is created with leaflet. So we have embedded an HTML widget in our dashboard as well. Again, we're seeing multiple pages, a row organization. Here we're seeing, again, a multiple pages and column organization. And one thing that may not be immediately obvious is that some of these are created with R, and some of them are created with Python. And we can see that the overall look is exactly the same. But those of you who code in one language or the other probably recognize some of the visualizations or some of the tables that are made. And you may be able to identify if the dashboard was created using R or Python code in the code cells.
Here's another one we're seeing similar to the earlier weather one, where we have a sidebar and also a row organization, and another one where we really only have two rows, a top row of value boxes and some text underneath it. So this is a dashboard which reporting on the models that are being deployed, another column organization, and another row organization. So one of the things we're going to talk a lot about in this video is how do you want to organize things in columns or in rows. And this is another one in columns as well. And this one is actually an interactive dashboard where we can see that as we play with these knobs, the visualizations are going to react to them as well.
And here's another interactive dashboard created with shiny elements. We can see a sidebar where we can check and uncheck some boxes, and that's going to control the behavior of the plots on the main panel of the dashboard.
The target Olympic dashboard
And another one, again, organized in rows. And here is the one that we are going to create by the end of the series of building Quarto dashboards. This dashboard uses data from the Olympics, excluding the most recent Olympics. So it gets pretty close to today, but not yet this year's Olympics as well. And we can see that we have organized our dashboard first in columns. So we're seeing a wider column of plots here, and then a narrower column of table and value boxes here. And we are also seeing two pages. We have summer and winter Olympics that we can scroll between. We're seeing a logo, and we're seeing a peculiar, perhaps, styling choice here as well. I've purposefully chosen a theme that's a little bit fun, and that is clearly not a default theme, so that it's obvious when you first look at it that we're going to play around with theming as well.
This particular dashboard was created with R, and this particular dashboard is created with Python. So we can see that between these two, we're looking at very, very similar content. In fact, it is exactly the same data being summarized in a very similar manner using similar packages. For the R version, we're going to use primarily packages from the tidyverse and make our visualizations with ggplot2 and our tables with the gt package. And if you're going to be following along in Python, you can grab the Python starter documents, and there's some starter code that you'll find in there that uses plot9 for the visualizations and greattables for the tables. And you'll be able to follow along with the examples in either language, though I will be primarily showing R examples while I'm live coding.
Dashboard basics: cards, rows, and columns
How do we get started? Starting with the R version on top, we can see that we have a QMD file with a YAML. And in the YAML, we have a title for our document, and we're setting format to dashboard. And everything is exactly the same in the Python version as well. A title, and then the notebook content goes outside of the YAML, so beneath it. So any pros or any visualizations or any tables that you're going to create, just like in a regular Quarto document, go underneath the YAML. And the only difference from an HTML output is that we're setting format to dashboard.
Let's start with some dashboard basics. Dashboards are composed of cards, and we're going to use the card multiple times throughout this video, and we're going to think about organizing our content for dashboards as cards. Cards can be arranged into rows and columns, and pages, tab sets, and sidebars allow for more advanced layout. So here we can see those three cards we started with, and then we've also added a sidebar to it as well.
We're going to make a dashboard step by step. We're going to do it first with R and then with Python, and this is going to be a simple dashboard, not the Olympic one just yet, but a simple dashboard so we can sort of wrap our heads around, what do we mean by cards and what do we mean by layouts? So here's our first dashboard in R. I'm going to start with sort of a bare bones QMD file with a YAML with just two fields, title and the format set to dashboard. And then we're going to add a card. Note that I actually haven't used the term card in my code anywhere. I have one code cell here where I'm loading the ggplot2 package, and then another code cell here where I'm making a pretty simple visualization, a scatter plot using the mpg dataset. If we render this as a dashboard, you will see that on the output, the code is not visible.
So by default, when our document, the format is set to dashboard, basically execute is set to false. Our code is hidden away, and the output of that code is placed in a card itself. And you can see over here that we can see the sort of the bounds of this card. This is not something I explicitly asked for in my code. Quarto automatically does that for me. And it also by default makes that card expandable as well.
So by default, when our document, the format is set to dashboard, basically execute is set to false. Our code is hidden away, and the output of that code is placed in a card itself.
Let's add another card. So here we're going to add another visualization. So we can see that we have three code cells so far in our document, one that simply loads a package and two that actually result in an output. Since we have only two that result in an output, so two plots, we end up with two cards this time. And we can see that by default, Quarto is going to place them on top of each other. So in other words, the orientation for the organization is in rows. Next, we're going to add titles to cards. And we're doing this by using options for our code cell defined with the hash pipe syntax. So the hash sign and then the pipe. And then we're setting a code cell option title. This may be a code cell option that you're not familiar with, if this is your first time making Quarto dashboards, as it is not an option that we commonly use in other formats. But when format is set to dashboard, these gain a meaning. And we will see that these texts that we've written here, highway versus city mileage and drive types, are going to be placed as titles on those cards. So we can see that we've gained a title. It has particular styling to it, sort of like faint gray background. And that text is placed as the titles of our cards. So bringing it all together, steps one through four, we end up with two cards because we had two code cells that generate an output. And each of these have their own titles as well.
Let's try to see how we would create the exact same output in Python. Step one, a bare bones QMD file with just a YAML with a title and format set to dashboard. Step two, we're going to add a card that produces a plot. So in this case, we've again added two code cells, one of them importing the packages that we're going to use, and one that is creating the visualization. And in the output, the one that actually creates the visualization turns into a card. And once again, the code is not ecode in our output. So we can see that the code is not visible, and we're only seeing the output, the visualization here. Let's add another card. So that's as simple as adding another code cell to our document. And we're going to see that, once again, the visualizations are in their own individual cards in row orientation. And you probably get the drill now. We can use the same code cell options regardless of the computational language of choice, and they're going to have the exact same behavior on the output as well. And our two dashboards are practically indistinguishable from each other.
Building the Olympic dashboard
So let's go ahead and build a dashboard ourselves. Before we go into building our first version of our Olympic dashboard, if you're interested in following along with the slides in this video, you would like to browse through them yourself. I've added the link to those on this slide. And if you're interested while you're watching the video to learn a little bit about making Quarto slides as well, I've linked to the GitHub repository where you can find the source code for the slide. So we're going to talk a lot about Quarto dashboards and coding up a Quarto dashboard. But the source code for the slides might also be helpful for learning a little bit about the Reveal.js output as well. To get started, go to the GitHub repository linked here. That is my username slash Olympic dash. And when you get to that repository, you will see that there is a button. This is set up as a template repository that you can say that you want to create a new repository using this one as its template. So I would recommend going ahead and doing that. This would be sort of like forking it, except that fork link will not be there anymore. You'll own the version of your repository, and you can commit and push to it easily.
Once you do that, clone that repository in your preferred IDE or editor. I'm going to be using RStudio for this video, but you're welcome to use VS Code or Positron or whatever you would like to use, or a bare bones code editor is totally fine as well. And then work on one of the following, depending on your preferred language. If you're going to be following along in R, you'll see a QMD file called Olympic dash dash R dash one, and similarly the Pi version for Python.
And our goal is to get to one of these outputs. Depending on whether you're using R or Python, you can see that we're going to create a dashboard. We're going to have a navigation bar on top with a logo and a title, and then our cards are organized. We can see that first in columns, and then within the first column, we've split it into two rows for two visualizations, and then a table on the side. So let's go ahead and do that. I am going to open up my clone version of that repository in RStudio, and I am going to open up the first R file here.
So in this starter file, our format is set to HTML. Let's go ahead and render this document just to see what it looks like so that we can identify the component. So the goal here is to focus on building a dashboard, not writing data analysis code. So I've given you all of that, but if you'd like to sort of browse through it, we are reading our data from the olympics.csv file from our data folder, doing a little bit of data wrangling in this code cell to get it in the format we need for our visualizations and our tables, and then we're going to create one visualization that's about medals by sport. We're going to then create another one that is medals by year, so how many medals of each type throughout the years, and then finally we have a table where we are calculating how many golds, silvers, and bronzes per country, and then reshaping that data frame into this format where we have one row per country, and then the number of medals are spread across the columns, and we're going to be organizing them in order of total medals.
So what is our first step going to be to turn this into a dashboard? Our first step is going to be to simply change the format to dashboard, and I'm not going to touch any of the rest of the document. I'm simply going to render this to see what do I get, what shakes out when I go from an analysis document like a report to a dashboard format. We can see that as we've seen in the earlier simple dashboard example, because we had three code cells that generated an output, we ended up with three cards, and these are organized in rows. Next, let's go ahead and add some titles to our code cells, and something to note here is that in my document, I actually have some headers to begin with. I can look in my document outline that I had these three headers, medals by sport, medals by year, and medals by country, and none of those words are visible in my output. This is because these headers end up telling Quarto something about how to organize the content, but the text that's actually associated with them is not reflected in your dashboard. Instead, we're going to capture that information as code cell titles.
So let's go ahead and take a look at our first code cell that creates a visualization. So that's here. I'm going to put away my outline, and I am going to add a title, medals by sport, and let's go ahead and render that.
I can see that that card has now gained a title, so I can do the same thing for my other code cells that generate plots or tables. This is going to be medals by year, and my table is going to be medals by country. Let's render that one more time.
All right. Next, we're going to add a GitHub icon and a link to the GitHub repository. So for me, that's going to be the GitHub repository that I've sent all of you to, and for yourself, you can grab the URL of the repository that you had created using this template, and that is something we are going to create or add to our YAML. Since we're adding additional YAML options for this format, I'm going to move that to the next line and indented with two spaces, add another column after that, and we're going to say that we want some navigation buttons, and this is going to be a GitHub button, and next, we're going to say that the link for this is going to be the URL that I had. So let's go ahead and render that. You can see that I have gained a GitHub icon here, and if I click on that, it's going to take me to my repository. So that's a neat way of sending the audience for your dashboard to your source code or really to anything else. So you can add other social buttons if you want to brand it with something personal to you as opposed to getting folks to your source code.
Next, we're going to add a logo. So if we take a look at our files in this repository, you'll see that there is a folder called Images. It is not mandatory to call this folder Images, but I recommend you put your data in a data folder. You put your images in an Images or Figures folder, and we can see that we have a logo here. It's Olympics logo, and it's an SVG file. So what we're going to want to do is place that ahead of the title of our dashboard. So I will add logo. This is in Images, and the name was Olympics-logo.svg.
And there we go. It is good practice whenever you have a visual in an output that you're sharing, and if this is an HTML output particularly, that others might be accessing with a screen reader to also add some alternative text. So you could add some alternative text to your visualizations as well. That's something we're going to get to a little bit later on in the series for building up this dashboard. But let's go ahead and add an alternative text for this logo. There's another YAML field that we can use for that. That is logo-alt, and I'll try to write a informative text about this. So let's say something like Olympics logo with multi-colored circles. While that information is not visible to us in this dashboard, it is accessible now to a screen reader.
Organizing cards into columns and rows
Okay. We're almost there, except if we take a look back at our slide to the goal that we want for this step of building up our dashboard, we need to reorganize our cards. So first of all, we said that the cards are originally, or in the first step, organized into columns. So we can see that column one has two plots and column two has the table. Let's go ahead and organize these into those two columns, and that is something we can do by simply changing the orientation of our dashboard. So the default orientation is rows. If I leave it as rows, we'll see that nothing actually changes in my output. That's how they were organized to begin with. Let's instead make it columns and see what shakes out of that. It's not going to quite get us there, but it will at least mean that the headers that we had, so these are the three headers that we had, are now indicating columns in our dashboard as opposed to rows in our dashboard. So what we're going to want to do next is to say that we want to split one of the columns into two. In general, because what these headings indicate is going to be dependent on the orientation you're choosing for your dashboard, and that that text will not be reflected in your output, I generally like to add some describing text to these as well. So we can say that, so metals by country is something that makes a column, and what we want are for these two headers to be rows within that first column. So how will we go about doing that? I'm going to add another second level heading here. I'm using the visual editor for doing that and the insert anything tool, but if you like you can go and type in the source editor as well, and if that's your preference that is going to be basically adding two hashes, so either way is fine. And I'm going to call this column plots, and then what we're going to do is those two second level headings that we had, we're going to turn them into third level headings. So we had metals by year and metals by sport, and let's go ahead and render this one more time.
So now what we have is a different organization for our dashboard. The second level headings indicate columns, so one column of plots and the other column of metals by country, and then my third level headings indicate a row and another row. Again, all of this text that indicates whether things are rows or columns are optional, but it's my personal preference because I like being able to see in the document outline when I'm jumping between things, and if I was to change the orientation I would need to go back and change those labels as well.
All right, it looks like we're getting there. Let's take a look at our goal, and one of the things that we are seeing is that the top visualization is a little bit taller than the bottom visualization. So we need a way of telling Quarto that the heights of these should not be equal to each other. So we can see here that when we leave things up to Quarto, the heights are equal to each other, and also the widths of the columns are equal to each other. So how will we go about doing that? Let's say that our metals by sport, I'm going to give this a height of 60 percent, and for my other one I'm going to give it a height of 40 percent. So instead of being equally split, so instead of being equally split, the top visualization is now going to be a little bit bigger. And one more look at our target. It looks like we are there. We have two columns of equal width. Within the first column we have two visualizations that are stacked on top of each other in cards, and maybe we can pop this out to full screen, and we can see that we've also adjusted their heights so that the top visualization is a little bigger than the other one. And we can see that these cards expand by default if we want to see them. There's plenty of improvements to make to this dashboard. We're still a few steps away from our goal of nicely styled and nicely colorized dashboard, but our first step at organizing the outputs that we had into rows and columns are done. So come back for part two where we talk about further dashboard components.
