Pins with Quarto

Published

2023-01-10

This document was rendered using Quarto 1.3.97.

The goals of this document are:

to show how to publish a web-based pins board using Quarto.
to set up a reprex to ask about best practices for including resources: in a Quarto website.

This is motivated by new capabilities to publish web-based boards in (the currently-dev version of) pins.

library("pins")
library("here")

The idea is:

create a board_folder(), write a pin to it, then create a manifest.
specify the folder as a resource to be included with the published site.

Then, I’ll show some code you can use to access the data.

Create board

Normally, I would create just one board. However, there’s something I’m not quite understanding about how we are meant to use Quarto’s resources: field, so I’m making an example.

board_one <- board_folder(here("data/board_one"), versioned = FALSE)
board_two <- board_folder(here("data/board_two"), versioned = FALSE)

For each board, write a pin:

board_one |> pin_write(mtcars, "mtcars", type = "json")

Creating new version '20230110T172500Z-c2702'
Writing to pin 'mtcars'

board_two |> pin_write(mtcars, "mtcars", type = "json")

Creating new version '20230110T172500Z-c2702'
Writing to pin 'mtcars'

For each board, write a manifest:

board_one |> write_board_manifest()

Manifest file written to root folder of board, as `_pins.yaml`

board_two |> write_board_manifest()

Manifest file written to root folder of board, as `_pins.yaml`

A manifest file will let consumers know about the pins and their versions.

Because the data is published independently from the code, I add /data/ to the .gitignore file.

Publish board

Here is the _quarto.yml file for this project:

project:
  type: website
  resources:
    - data/board_one/
resources:
  - data/board_two/

As you can see, I have made a resource entry for each board in different places in the file.

When I render the file, I get a set of warnings:

WARNING: File 'data/board_one/mtcars/20221223T162805Z-c2702' was not found.
WARNING: File 'data/board_one/mtcars/20221223T162805Z-c2702/data.txt' was not found.
WARNING: File 'data/board_one/mtcars/20221223T162805Z-c2702/mtcars.json' was not found.

The resources entry for data/board_one results in only the _pins.yaml file being copied to _site, whereas the entire directory structure for data/board_two is copied to _site.

In the site resources documentation, it encourages us to put resources: within project:.

Questions

Is resources meant to copy folders recursively?
- if so, what is the right syntax?
I found the top-level resources: by accident. Is it meant to act differently from the version in project:?

Consume board

When you publish your Quarto site, for example to GitHub Pages, the board is available as a part of the website. Anyone can access the data using board_url(), like so:

board <- board_url("https://ijlyttle.github.io/quarto-pins/data/board_two/")

board |> pin_list()

[1] "mtcars"

board |> pin_versions("mtcars")

# A tibble: 1 × 3
  version                created             hash 
  <chr>                  <dttm>              <chr>
1 20221226T224337Z-c2702 2022-12-26 22:43:37 c2702

board |> pin_read("mtcars") |> head()

                   mpg cyl disp  hp drat    wt  qsec vs am gear carb
Mazda RX4         21.0   6  160 110 3.90 2.620 16.46  0  1    4    4
Mazda RX4 Wag     21.0   6  160 110 3.90 2.875 17.02  0  1    4    4
Datsun 710        22.8   4  108  93 3.85 2.320 18.61  1  1    4    1
Hornet 4 Drive    21.4   6  258 110 3.08 3.215 19.44  1  0    3    1
Hornet Sportabout 18.7   8  360 175 3.15 3.440 17.02  0  0    3    2
Valiant           18.1   6  225 105 2.76 3.460 20.22  1  0    3    1

Because the pin above has to be published before it is consumed, we are seeing a previous publication of the pin.