Quarto Dashboards: from zero to publish in one hour

Transcript#

This transcript was generated automatically and may contain errors.

It looks like it's that we can get going here now, and I am pleased to announce this demo on Quarto Dashboards from zero to publish in one hour by Vinay, and I will turn it over to you. All right, wonderful. Thank you very much, and thanks for having me.

I'm going to share the link to the slides one more time, and I'll do so again when we get close to the demo piece of it. So if you're here, you probably know about Quarto and Dashboards, but Quarto is an open-source scientific and technical publishing system, and the goal of Quarto is to make the process of creating and collaborating dramatically better.

With Quarto, you can weave together narrative, text, and code to produce elegantly formatted output. This output could be an HTML file, a PDF file, a Word file, and a lot more, including Dashboards since Quarto 1.4. And we are at, so I'll be using the pre-release version of Quarto, which is 1.8, which I happen to have installed, but if you have 1.7 installed, which is the release version, that's totally fine as well. There's been no changes regarding any of the things that I'll be demoing today.

So it has been around for some time, though it is one of the newer features of Quarto as opposed to one of the original ones. So if you are going to be following along as I demo, which may be a bit of a ride because we're going to go through some things quickly, but especially if you're thinking that you may do this in your own time later, make sure that you check your Quarto version if you haven't installed it over the last couple of years and make sure that things are up to date.

So the title of this demo, From Zero to Quarto Dashboard, is a lie. As you can see, we're not going to start with zero. But all we're starting with sort of is the analysis portion of things that's done. And we're going to turn it into a dashboard.

Converting the document to a dashboard

I am going to start by taking out this table of contents. The idea of table of contents doesn't really make sense in a Quarto dashboard. And I am then going to simply say, let's make this a dashboard. And let's see what happens.

So we get some things that look good and some things that make no sense whatsoever. My first level headings, so my headings that were overview and later on, if I go in my outline schedule, ended up being the two pages of my dashboard. And then every single output from an R code cell ended up being a card, one of these expandable cards. So the content that I want for my dashboard is here. But it's obviously not organized in the way that I would like it to be organized. So let's go ahead and tackle this organization problem first.

We are going to start with sort of creating the right hierarchy for our dashboard so that we can have the rows and columns as we like.

So we have my overview. And this is going to be my first page. And remember that my dashboard was organized in columns. So the first thing that I'm going to do is to say that I want my orientation to be columns. And then we are going to create these two columns. One of them is the in-person program. That was a much wider area because there's a lot more going on the three days of in-person program than the virtual program. So I'm going to give this a width of 70%.

And then I am going to go to my virtual program and give that a width of 30% adding up to 100. And let's go ahead and click on render on save just because we're going to be doing this over and over. So my goal now is to create the two columns that I'm interested in, which seems to have happened. And let's also observe a few other things that happened.

The title for my page, my first level heading, the word overview is in my code and also visible here. Unfortunately, though, or maybe fortunately, I'm not sure, but the title for the second level heading, which basically identified the columns is not visible here. So the text that you see here in the code is optional. We could have completely avoided it. What I generally like to do is I like to leave myself notes about what these things create.

So this is going to be a column. And then I want to still make a title for that column. And I'm going to do that with something like this. Let's make it a bolded text in-person program.

So now I have a card that says in-person program in it. The expand buttons coming for free with Quarto dashboards is great for something like a plot and really silly for something like a text box like this. So we can actually have finer control on these cards, even though each piece of text or each piece of computational output gets a card by default. We can manually create cards with fence divs as well. So that's three columns. And then I'm going to say this is a card. And then I can say that I don't want it to be expandable. So I'm going to set expandable to false.

So now we go ahead and we can see that we're going to get that title. And we are not going to be seeing the button for expanding things. I also would like this to be much skinnier. So I'm going to add another layer. So let's call this title. And we used width for columns. So we're going to use height for rows. Let's make this 5%, something tiny.

All right, that looks a lot better to me. And let me go ahead and make similar changes on the virtual program as well. So what were some things that we did here? We said this denotes a column. And this is going to be the virtual program.

Adding value boxes

So now we have two title cards that are equal height that we have here. Let's go ahead and tackle now this tabular output. Remember, these are going to be value boxes instead. So instead of presenting this information as a table, we're going to present each piece of this information as value boxes. So the first thing I'm going to do is I'm going to actually go ahead and remove the table from printing. So we do want the values to be calculated, but we don't want them printed as a table.

And instead, what we're going to do is let's create another row. These are my value boxes. Remember, this text is optional. It's just something that's helpful for me to remember what's in that row. And it also then gets presented in the document outline as well, which is nice. And let's give it a width. I'm going to say 30%.

And let's go ahead and create those value boxes. Each one of these value boxes can be created as a code cell. And there are a few pieces of information we want to give for these code cells. First of all, I want to set the code cell option content to value box. And then I want to give it a title. Let's start with the keynote. That was the first value box in our dashboard. And then let's go ahead and actually make the value box itself. In R, we can use a list for that.

The icons are bootstrap icons. So I'm going to use a mic for this. The color. So here is where I'm going to cheat a little bit. I have pre-programmed some colors here. And so we're just going to use these as opposed to spending a bunch of time browsing through colors while we're also trying to build the dashboard in an hour. I'm going to use the keynote color. And the value. So we want this number five. How do we get this number five?

We can take this data frame or table. We can filter for where session simplified. Since I didn't run that code in my console, it's not helping me, is equal to keynote. And then we can say pull the column in. So let's go ahead and see what that looks like.

All right. So we have our first value box. And we need to make a bunch of these. This is going to be the slightly annoying piece where we're making a bunch of them. But hopefully, it is not too bad. I think we had five of these things to make.

And they are going to be tutorials. So after keynotes, we have tutorials. And then talks. Lightning talks. And posters. As you can imagine, we can go ahead and change what we're filtering for easily here.

So this gives us the value boxes that we wanted. And we're probably going to want to look for some new icons for these. So let's go ahead and look for bootstrap icons. So what I usually do is maybe I go somewhere like this. And maybe for the tutorials, I might want something like code. So let's go ahead and say I'd like code square. Code square.

And we can go ahead for tutorials and change that icon to code square. For talks, we're going to do a mic that's not filled. For lightning, it turns out there is a lightning icon. And for poster, I think what I had originally was a clipboard. Which is not a poster. But that was the closest image I could find to what I think of as what a scientific poster might look like at a conference. So there we go. We have our value boxes. They're equally spaced, equally sized. The space that we had allotted has now been sort of dedicated to these value boxes themselves.

Sizing and theming the plots

The next thing we're going to want to do is deal with these figures that are looking truly awful at this point. So first of all, let's go ahead and deal with the first one, which is the daily count.

And once again, I'm going to say this is a row. And I would like it to be a height of, let's say, a height of 30%. Let's go ahead and see what that gets us in terms of the space.

And the next one with beams is also a row. And this one, I think all we have left is 40%. Now, remember that we want a little bit more here in terms of these cards. So let's go ahead and give them titles. We can call this daily session counts. And for the themes, we can call it emerging themes.

And those are going to get the nice card title treatment in the code cells, obviously making the plot shrink a lot more. But we'll get to that in a sec.

So plot sizing is tricky, particularly when you're working in a limited area, like the viewer of your IDE. So I'm going to go ahead and pop this out first of all. Let's go ahead and get rid of this window here. I'm going to go ahead and pop this out and make it a little bit bigger.

So things look a little bit better here. And then let's go ahead and play with figure sizing like you usually do in Quarto. So fig height, I want it to be pretty skinny in terms of the height. I'm going to say 1.75. And fig width, we want it to be wide. So let's go ahead and try 10 and see what that gets us.

All right, there we go. That's looking a lot better and a lot more legible.

And then the other thing that we're going to want to do is a similar treatment for the themes plot as well. So let's go ahead and grab what we've done here. And use sort of similar sizes. I'm going to say 2.5 and 8 here.

All right, if we were to just forgive ourselves for a second from the second column and just focus on the first column, things are looking pretty good.

Adding light and dark themes with brand.yaml

But one of the things I showed earlier was that we're going to also have a light and a dark theme in place. And right now, we don't have that. So why don't we go ahead and tackle that next? And then we're going to come back to finishing up the second column.

So in order to have a light and a dark theme, you have a variety of options. And so I'd like to talk a little bit about a newer way, instead of writing an SCSS file from scratch, using the brand.yaml functionality in Quarto to create themes.

So I'm going to say that we are going to create a new YAML field called brand. And we're going to have a light and a dark option for it. And then these blanks are supposed to be two files that we reference. Let's go ahead and create those files first. So I'm going to go ahead and I can probably just do it here. Let's see, a new folder that I might call brand. And in that new folder, I'd like to create a new file called lightbrand.yaml. And also, we're going to create a darkbrand.yaml as well.

Okay, let's start with a light one. One, something that might be a little bit easier to tackle. And let's make some choices. So some of the things that we might want to tackle here is the colors. So let's start. Let's go ahead and denote some colors.

And one nice thing that you can do in a brand.yaml file is give a palette. So you get to name your own color. So I'm going to name a light gray, a dark gray, and a blue that I want to use that matches with the UseR blue that we were using on the website for UseR. And then we can set these particular colors to particular elements of the dashboard.

So bear with me while I just write down these colors. In general, for dark, I like to use a dark gray as opposed to a black, particularly when doing these light and dark themes. I think it tends to be a little bit softer.

Okay, so now that I have encoded these colors, I can say that I want the foreground to be dark gray. So that's going to be the main text. I want the background to be white. And I want the primary, so something like the navigation bar, for example, to be light gray as well.

All right, and then what we are going to do is say this is going to be the light brand.yaml. I'm currently getting an error when I try to render this because obviously I have some syntax that doesn't make sense here. So let's go ahead and grab these same colors, put them in the dark brand, but this time change some things around.

The foreground should be light gray. The background should be dark gray. And the primary should be a medium gray. I'll add that in a second. And the secondary should be medium gray as well. So let's go ahead and add that medium gray too.

Okay, let's see if now we can render this again. See if we have gained that dark light toggle. And we have, in fact. And we can see that the color on the navigation bar is changing. The color of the background is changing. The cards themselves are getting affected. The plots look awful white in the middle of them. And it looks like we may want to play around with some more colors as well in terms of how some of these colors are presenting in front of the darker colors when we go to dark mode.

Light and dark plot renderings

Let's go ahead and tackle the plots first because that I think is going to be most important and most useful for folks. So another newer Quarto feature. Let me go ahead and get to this daily session count.

A newer Quarto feature is being able to give two plots in a code cell and then set the renderings code cell option. And we can just say this is going to be the first plot is going to be the light and the second plot is going to be the dark. So my first plot is basically this plot here. I'm going to say this is my light plot.

And my second plot, I need to make it as well. But because I'm building with ggplot, I can probably just go ahead and add more to the theme. A few things that I might want to do is change the plot background. Color, so fill should be dark gray that we've been using. The color, which is the boundary, should be dark gray that we've been using.

Another thing we may want to change is the axis text. To make it a lighter color. And also, similarly, the text in the, for the, for the panes, when we're facet them, the titles of the panes as well. Let's make those white too.

So you can see that this now is a code cell that outputs two plots. But what's going to happen is because we've used this renderings option here, it's not just going to print the two plots every time we render it, it's going to switch between the two plots depending on whether we are in dark or light mode. So here is the plot in light mode and here is the plot in dark mode.

So the way we're able to achieve a more cohesive look, it is extra work for us, but the way we're able to achieve it is simply by making that second plot as well and setting the renderings option. You can imagine we would do similar things for the plot, the second plot as well. So let's go ahead, not be lazy, and do that too for completeness.

So the way we're able to achieve a more cohesive look, it is extra work for us, but the way we're able to achieve it is simply by making that second plot as well and setting the renderings option.

Create a light and dark and say this is going to be the light. And let me go ahead and make a dark version of the plot as well.

And I'm going to go ahead and grab this. And let's see if we might just basically bring in similar theme elements. Most importantly, there are no axis text here, but most importantly, the plot background.

Now let's go ahead and render this and take a look. Here is what it looks like in the dark mode and here is what it looks like in light mode. The dark blue text that is sort of like around here looks great against light background, but it's really hard to decipher against dark background.

So chances are this is going to be an iterative process for you where you play with other aspects of the plot as you render your document in light and dark. And you might say, OK, maybe the high value should be white, not that darker blue. And white was not a color that we had saved. So we'll use ours white here.

And so now things are looking better in dark mode as well. So we have now shown that we can do this with plots.