Skip navigation

Category Archives: Quarto

I’ve been (mostly) keeping up with annual updates for my R/{sf} U.S. foliage post which you can find on GH. This year, we have Quarto, and it comes with so many batteries included that you’d think it was Christmas. One of those batteries is full support for the Observable runtime. These are used in {ojs} Quarto blocks, and rendered versions can run anywhere.

The Observable platform is great for both tinkering and publishing (we’re using it at work for some quick or experimental vis work), and with a few of the recent posts, here, showing how to turn Observable notebooks into Quarto documents, you’re literally two clicks or one command line away from using any public Observable notebook right in Quarto.

I made a version of the foliage vis in Observable and then did the qmd conversion using the Chrome extension, tweaked the source a bit and published the same in Quarto.

The interactive datavis uses some foundational Observable/D3 libraries:

In the JS code we set some datavis-centric values:

foliage_levels = [0.01, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6]
foliage_colors = ["#83A87C", "#FCF6B4", "#FDCC5C", "#F68C3F", "#EF3C23", "#BD1F29", "#98371F"]
foliage_labels = ["No Change", "Minimal", "Patchy", "Partial", "Near Peak", "Peak", "Past Peak"]
week_label = ["Sept 5th", "Sept 12th", "Sept 19th", "Sept 26th", "Oct 3rd", "Oct 10th", "Oct 17th", "Oct 24th", "Oct 31st", "Nov 7th", "Nov 14th", "Nov 21st"]

We then borrow the U.S. Albers-projected topojson file from the Choropleth example notebook and rebuild the outline mesh and county geometry collections, since we need to get rid of Alaska and Hawaii (they’re not present in the source data). We do this by filtering out two FIPS codes:

counties = {
  var cty = topojson.feature(us, us.objects.counties);
  cty.features = cty.features.filter(
    (d) => (d.id.substr(0, 2) != "02") & (d.id.substr(0, 2) != "15")
  );
  return cty;
}

I also ended up modifying the source CSV a bit to account for missing counties.

After that, it was a straightforward call to our imported Choropleth function:

chart = Choropleth(rendered2022, {
  id: (d) => d.id.toString().padStart(5, "0"), // this is needed since the CSV id column is numeric
  value: (d) => d[week_label.indexOf(week) + 1], // this gets the foliage value based on which index the selected week is at
  scale: d3.scaleLinear, // this says to map foliage_levels to foliage_colors directly
  domain: foliage_levels,
  range: foliage_colors,
  title: (f, d) =>
    `${f.properties.name}, ${statemap.get(f.id.slice(0, 2)).properties.name}`, // this makes the county hover text the county + state names
  features: counties, // this is the counties we modified
  borders: statemesh, // this is the statemesh
  width: 975,
  height: 610
})

and placing the legend and scrubbing slider.

The only real difference between the notebook and qmd is the inclusion of the source functions rather than use Observable’s import (I’ve found that there’s a slight load delay for imports when network conditions aren’t super perfect and the inclusion of the source — WITH copyrights — makes up for that).

I’ve set up the Quarto project so that renders go to the docs/ directory, which makes it easy to publish as a GH page.

FIN

Drop issues on GH if anything needs clarifying or fixing and go experiment! You can’t break anything either on Observable or locally that version control can’t fix (yes, Observable has version control!).

Some things to consider modifying/adding:

  • have a click take you to a (selectable?) mapping service, so folks can get driving directions
  • turn the hover text into a proper tooltip
  • speed up or slow down the animation when ‘Play’ is tapped
  • use different colors
  • bring in older datasets (see the foliage GH repo) and make multiple maps or let the user select them or have them compare across years

My previous post announced a Rust-based command line tool for generating Quarto projects from Observable Notebooks.

Some folks may not want to use yet-another command line tool, and it dawned on me that it’d be more convenient to just do the conversion in-browser when one is already on a Notebook page. So, I dusted off some very creaky Chrome extension skills and put together an extension for doing just that.

It’s pretty straightforward:

  • navigate to a Notebook you want to serialize to a Quarto project
  • press the button
  • profit!

You can download individual resources by hand or just use the zip file that automagically downloaded.

screen capture of observable notebook showing how to press the quartize button

screencap showing the aftermath of the quartize process with annotations

vs code screencap showing the downloaded quarto project in source and render

The previous post had some hacky R code to grab seekrit JSON data in ObservableHQ (OHQ) Notebooks and spit out a directory with a Quarto qmd and any associated FileAttachments. Holding firm to my “no more generic public R packages” decree, that’s as far as the R code for that utility is going to get.

Quarto, by design, is not married to the R ecosystem. This should help it get more traction in and outside of the broader data science crowd than R Markdown was able to attain. One big element that makes Quarto enticing to me is that it ships with the Observable runtime and stdlib. Observable javascript tools make coding up reactive data visualizations and analyses fun, but I still really dislike using a browser for data science work. I’d much rather use Quarto’s {ojs} sections in a proper editor/IDE when iterating over a concept.

I also learn best by example-first -> experiment-second. Up until now, I’ve been doing the example-ing and experiment-ing over at OHQ. When I discovered that the OHQ notebook code and metadata ships with the HTML page of the notebook (in a JSON <script> block at the end of the document) I just had to build a tool to yank that out and turn it into a Quarto project.

The R code in the previous post is fine for R folks (someone should 100% take that, make it nicer, and turn it into a small package with an RStudio addin and CLI wrapper; no credit back to me is required), but — as noted above — Quarto is not just for R folks. Rather than confine a conversion utility to some scripting language, I decided to port the R experiment over to Rust. That is how ohq2quarto was born.

You can grab Windows & macOS binaries from the Releases, or just:

cargo install --git https://github.com/hrbrmstr/ohq2quarto

to install it if you’re on Linux or already have a Rust environment setup. I’m working on the configuration of a GitHub Action that will make shipping binaries for all platforms stupid simple and automated.

When run in verbose mode, you’ll see something like this when converting a notebook:

$ ohq2quarto --ohq-ref @hrbrmstr/just-one-more-thing --output-dir ./examples --verbose 
      Title: Just One More Thing
       Slug: just-one-more-thing
  Author(s): boB Rudis
  Copyright: Copyright 2022 boB Rudis
    License: "mit"
 Observable: https://observablehq.com/@hrbrmstr/just-one-more-thing

A look at examples shows:

$ tree examples
├── _quarto.yml
├── columbo_data.csv
└── just-one-more-thing.qmd

The utility made the directory, created the qmd and downloaded the FileAttachment.

This is what the first few lines of the qmd look like:

$ head -16 examples/just-one-more-thing.qmd
---
title: 'Just One More Thing'
author: 'boB Rudis'
format: html
echo: false
observable: 'https://observablehq.com/@hrbrmstr/just-one-more-thing'
---

```{ojs}
md`# Just One More Thing`
```

```{ojs}
md`This week, Chris Holmes tweeted something super dangerous:`
```

FIN

I’ve tried it on some seriously complex OHQ notebooks and it seems to do what I’ve claimed it does on the tin’s label. If you run into issues, or have some feature requests, please drop an issue in the repo.

Quarto is amazing! And, it’s eating the world! OK. Perhaps not the entire world. But it’s still amazing!

If you browse around the HQ, you’ll find many interesting notebooks. You may even have a few yourself! Wouldn’t it be great if you could just import an Observable notebook right into Quarto? Well, now you can.

#' Transform an Observable Notebook into a Quarto project
#' 
#' This will yank the cells from a live Observable notebook and turn it into a Quarto project,
#' downloading all the `FileAttachments` as well.
#' 
#' @param ohq_ref either a short ref (e.g. `@@hrbrmstr/just-one-more-thing`) or a full
#'     URL to a published Observable notebook
#' @param output_dir quarto project directory (will be created if not already present)
#' @param quarto_filename if `NULL` (the default) the name will be the slug (e.g. `just-one-more-thing`
#'     as in the `ohq_ref` param eample) with `.qmd` suffix
#' @param echo set `echo` to `true` or `false` in the YAML
ohq_to_quarto <- function(ohq_ref, output_dir, quarto_filename = NULL, echo = FALSE) {

  ohq_ref <- ohq_ref[1]
  if (grepl("^@", ohq_ref)) ohq_ref <- sprintf("https://observablehq.com/%s", ohq_ref)

  output_dir <- output_dir[1]
  if (!dir.exists(output_dir)) dir.create(output_dir)

  quarto_filename <- quarto_filename[1]

  pg <- rvest::read_html(ohq_ref)

  pg |> 
    html_nodes("script#__NEXT_DATA__") |> 
    html_text() |> 
    jsonlite::fromJSON() -> x

  meta <- x$props$pageProps$initialNotebook
  nodes <- x$props$pageProps$initialNotebook$nodes

  if (is.null(quarto_filename)) quarto_filename <- sprintf("%.qmd", meta$slug)

  c(
    "---", 
    sprintf("title: '%s'", meta$title), 
    "format: html", 
    if (echo) "echo: true" else "echo: false",
    "---",
    "",
    purrr::map2(nodes$value, nodes$mode, ~{
      c(

        "```{ojs}",
        dplyr::case_when(
          .y == "md" ~ sprintf("md`%s`", .x),
          .y == "html" ~ sprintf("html`%s`", .x),
          TRUE ~ .x
        ),
        "```",
        ""
      )

    })
  ) |> 
    purrr::flatten_chr() |> 
    cat(
      file = file.path(output_dir, quarto_filename), 
      sep = "\n"
    )

  if (length(meta$files)) {
    if (nrow(meta$files) > 0) {
      purrr::walk2(
        meta$files$download_url,
        meta$files$name, ~{
          download.file(
            url = .x,
            destfile = file.path(output_dir, .y),
            quiet = TRUE
          )
        }
      )
    }
  }

}

You can try that out with my Columbo notebook:

ohq_to_quarto(
  ohq_ref = "@hrbrmstr/just-one-more-thing", 
  output_dir = "~/Development/columbo",
  quarto_filename = "columbo.qmd",
  echo = FALSE
)

That will download the CSV file into the specified directory and convert the cells to a .qmd. You can download that example file, but you’ll need the data to run it (or just run the converter).

This is what the directory tree looks like after the script is run and the document is rendered:

columbo/
├── columbo.html
├── columbo.qmd
├── columbo_data.csv
└── columbo_files
    └── libs
        ├── bootstrap
        │   ├── bootstrap-icons.css
        │   ├── bootstrap-icons.woff
        │   ├── bootstrap.min.css
        │   └── bootstrap.min.js
        ├── clipboard
        │   └── clipboard.min.js
        ├── quarto-html
        │   ├── anchor.min.js
        │   ├── popper.min.js
        │   ├── quarto-syntax-highlighting.css
        │   ├── quarto.js
        │   ├── tippy.css
        │   └── tippy.umd.min.js
        └── quarto-ojs
            ├── quarto-ojs-runtime.js
            └── quarto-ojs.css

The function has not been battle tested, and it’s limited to the current functionality, but it should do what it says on the tin.

I’ll turn this into a Rust binary so it’s more usable outside of the R ecosystem.

You can try out a fledgling Rust version here.