Quarto Dashboard

for impactful and visual communication

Christophe Dervieux

Posit PBC

September 25, 2024

What is ?

An open-source, scientific and technical publishing system

Building on standard Markdown with features essential for scientific communication

Extended Pandoc Markdown for textual content
Multi-engine support for configurable computations
Various Output Formats

A schematic representing the multi-language input (e.g. Python, R, Observable, Julia) and multi-format output (e.g. PDF, html, Word documents, and more) versatility of Quarto.

With Quarto …

you can weave together narrative and code to produce elegantly formatted output as documents, web pages, blog posts, books and more…

Which includes… Dashboards

A schematic representing the multi-language input (e.g. Python, R, Observable, Julia) and dashboard output.

How to use Quarto?

Quarto is a command line interface (CLI) that renders Jupyter notebook (.ipynb) or plain text formats (.qmd, .md) into reports (PDF, Word, HTML …), books, websites, presentations (Revealjs, Powerpoint, …) and more.

$ quarto --help

Usage:   quarto
Version: 1.5.57

Description: 

  Quarto CLI

Options:

  -h, --help     - Show this help.
  -V, --version  - Show the version number for this program.

Commands:

  render     [input] [args...]     - Render files or projects to various document types.
  preview    [file] [args...]      - Render and preview a document or website project.
  serve      [input]               - Serve a Shiny interactive document.
  create     [type] [commands...]  - Create a Quarto project or extension
  use        <type> [target]       - Automate document or project setup tasks.
  add        <extension>           - Add an extension to this folder or project
  update     [target...]           - Updates an extension or global dependency.
  remove     [target...]           - Removes an extension.
  convert    <input>               - Convert documents to alternate representations.
  pandoc     [args...]             - Run the version of Pandoc embedded within Quarto.
  typst      [args...]             - Run the version of Typst embedded within Quarto.
  run        [script] [args...]    - Run a TypeScript, R, Python, or Lua script.
  install    [target...]           - Installs a global dependency (TinyTex or Chromium).
  uninstall  [tool]                - Removes an extension.
  tools                            - Display the status of Quarto installed dependencies
  publish    [provider] [path]     - Publish a document or project to a provider.
  check      [target]              - Verify correct functioning of Quarto installation.
  help       [command]             - Show this help or the help of a sub-command.

How to use Quarto?

Render and Preview

Render to output formats:

# ipynb notebook
quarto render notebook.ipynb
quarto render notebook.ipynb --execute
quarto render notebook.ipynb --to pdf
quarto render notebook.ipynb --to dashboard

# plain text qmd
quarto render notebook.qmd 
quarto render notebook.qmd --to docx

Live preview server:

# ipynb notebook
quarto preview notebook.ipynb
quarto preview notebook.ipynb --execute
quarto preview notebook.ipynb --to revealjs

# plain text qmd
quarto preview notebook.qmd
quarto preview notebook.qmd --to revealjs

How to use Quarto?

Quarto integrates with other tools.

Quarto Workflow

Computations: Jupyter (and Knitr and ObservableJS)

Markdown: Pandoc
with many enhancements

Output: Documents, presentations, websites, books, blogs, …

Render Notebook to HTML (default options)

Render Notebook to HTML (document level options)

Render Notebook to HTML (document and cell level options)

Render Notebook to Revealjs — https://quarto.org/docs/presentations/revealjs/

Peeking at Dashboard Examples

How to build a Quarto Dashboard ?

Notebook ➝ HTML

olympicdash-py.qmd

---
title: "Olympic Games"
format: html
---

# notebook content goes here...

Notebook ➝ Dashboard

olympicdash-py.qmd

---
title: "Olympic Games"
format: dashboard
---

# notebook content goes here...

Layout

Layout - Cards

Dashboards are composed of cards.

Layout - Rows and columns

Cards are arranged into rows and columns.

Layout - Advanced

Sidebars, tabsets, and pages allow for more advanced layouts.

Dashboard Components

Navigation Bar and Pages
— Icon, title, and author along with links to sub-pages (if more than one page is defined).
Sidebars, Rows & Columns, and Tabsets
— Rows and columns using markdown heading (with optional attributes to control height, width, etc.). Sidebars for interactive inputs. Tabsets to further divide content.
Cards (Plots, Tables, Value Boxes, Content)
— Cards are containers for cell outputs and free form markdown text. The content of cards typically maps to cells in your notebook or source document.

All of these components can be authored and customized within notebook UI or plain text qmd.

Navigation Bar and Pages

---
title: "Olympic Games"
format: 
  dashboard:
    nav-buttons: [github]
    github: https://github.com/posit-conf-2024/olympicdash
logo: images/olympics-logo.svg
logo-alt: "Olympics logo with multicolored circles."
---

# 🌞 Summer Olympics

# ❄️ Winter Olympics

Sidebars: Page Level

---
title: "Sidebar"
format: dashboard
---
    
# Page 1

## {.sidebar}

```{python}
```

## Column 

```{python}
```

```{python}
```

Sidebars: Global

---
title: "Global Sidebar"
format: dashboard
---
    
# {.sidebar}

Sidebar content (e.g. inputs)

# Plot

```{python}
```

# Data

```{python}
```

Layout: Rows

---
title: "By Rows"
format: dashboard
---
    
## Row {height=70%}

```{python}
```

## Row {height=30%}

```{python}
```

```{python}
```

Row for header content is used as example here.
Header name can be anything.

Layout: Columns

---
title: "By Columns"
format: 
  dashboard:
    orientation: columns
---
    
## Column {width=60%}

```{python}
```

## Column {width=40%}

```{python}
```

```{python}
```

Cards

Automatically created from cell’s output or Markdown content

## Column - Medals by sport and year {width=65%}

### Row - Medals by sport {height=60%}

```{python}
#| label: summer-medals-by-sport
#| title: Medals by sport

# Lump the sport column to top 15 categories, grouping others as Other
top_15_sports = summer_olympics["sport"].value_counts().nlargest(15).index
summer_olympics["sport"] = summer_olympics["sport"].apply(lambda x: x if x in top_15_sports else "Other")

# Convert the sport column to a categorical type with order based on frequency, and reverse the order
summer_olympics["sport"] = pd.Categorical(summer_olympics["sport"], categories = summer_olympics["sport"].value_counts().index[::-1])

# Move the Other category of the sport column to the beginning
new_order = ["Other"] + [cat for cat in summer_olympics["sport"].cat.categories if cat != "Other"]
summer_olympics["sport"] = summer_olympics["sport"].cat.reorder_categories(new_order)

# Plot
(
    ggplot(summer_olympics, aes(x = "sport", fill = "medal")) +
    geom_bar() +
    coord_flip() +
    guides(fill = guide_legend(reverse = True)) +
    scale_fill_manual(
        values = {"Gold":"#d4af37", "Silver":"#c0c0c0", "Bronze":"#cd7f32"}
    ) +  
    labs(
        x = "",
        y = "",
        fill = "Medal"
    ) +
    theme_minimal() +
    theme(
        legend_position = "inside",
        legend_position_inside = (0.9, 0.2),
        legend_direction = "horizontal",
        legend_background = element_rect(fill = "white", color = "gray"),
        figure_size = (11, 2)
    )
)
```

Cards

Automatically created from cell’s output or Markdown content

Value Boxes

## Row

```{python}
#| component: valuebox
#| title: "Current Price"
dict(icon = "currency-dollar",
     color = "secondary",
     value = get_price(data))
```

```{python}
#| component: valuebox
#| title: "Change"
change = get_change(data)
dict(value = change['amount'],
     icon = change['icon'],
     color = change['color']) 
```

Value Boxes

## Column - Medals by country {width=35%}

### Row - Value boxes {height=30%}

::: {.valuebox icon="award-fill" color="#d4af37"}
Most golds: 

`{python} str(count_most_gold_medals)`

`{python} most_gold_medals`
:::

::: {.valuebox icon="award-fill" color="#c0c0c0"}
Most silvers: 

`{python} str(count_most_silver_medals)`

`{python} most_silver_medals`
:::

::: {.valuebox icon="award-fill" color="#cd7f32"}
Most bronzes: 

`{python} str(count_most_bronze_medals)`

`{python} most_bronze_medals`
:::

`{python} str(count_most_gold_medals)` is an inline code syntax that is supported in Quarto to easily mix Markdown text and computation output values.

Tabsets

---
title: "Palmer Penguins"
format: dashboard
---
    
## Row

```{python}
```

## Row {.tabset}

```{python}
#| title: Chart 2
```

```{python}
#| title: Chart 3
```

Styling a Dashboard

---
title: "Olympic Games"
format: 
  dashboard:
    orientation: columns
    nav-buttons: [github]
    github: https://github.com/posit-conf-2024/olympicdash
    theme:
      - sketchy
      - style/olympicdash.scss
logo: images/olympics-logo.svg
logo-alt: "Olympics logo with multicolored circles."
---

Bootstrap & Bootswatch Themes:
Quarto Dashboard is based on Bootstrap with +20 themes from Bootswatch available

Customization through Quarto themes files: Based on SASS, an easy way to declare new themes or variations to be layered into SCSS to be compiled to CSS

Quarto Theme File

olympicdash.scss

/*-- scss:defaults --*/

// colors

$navbar-bg: #52515e;
$navbar-fg: #F0F0F0;

$link-color: #ae8b2d;
$hover-color: lighten($link-color, 40%);

/*-- scss:rules --*/
.card-header {
  background-color: #ae8b2d50;
}

.nav-item > a:hover {
  color: #ae8b2d;
}

.nav-link {
  color: #F0F0F0;
}

.tabset .nav-link {
  color: #52515e;
}

.value-box {
  text-align: center;
}

Learning More

A lot more can be done with Quarto Dashboard:

Deep dive at https://quarto.org/docs/dashboards/

Advanced features:

And about Quarto ?