The pins package supports back-and-forth collaboration for publishing
and consuming using, for example,
board_s3(). The goal of
this vignette is to show how to publish a board of pins to a website,
bringing your pins to a wider audience. How does this work?
board_url()offers read-only collaboration.
write_board_manifest(). A manifest contains a list of pins and versions, enabling a
board_url()to read like a
The steps for publishing a board that can be read by consumers using
The first and last steps will be specific to how you deploy your board on the web; we discuss options in the Publishing platforms section. Regardless of platform, you’ll write the pins and the manifest the same way.
For this first demonstration, we’ll start by creating a board, and finish by showing how the board works after being served.
library(pins) <- board_temp(versioned = TRUE)board
We’re using a temporary board for this demonstration, but in
practice, you might use
board_folder() in a project folder
or GitHub repo, or perhaps
Let’s make the
mtcars dataset available as a JSON
%>% pin_write(mtcars, type = "json") board #> Using `name = 'mtcars'` #> Creating new version '20120304T050607Z-c4fcd' #> Writing to pin 'mtcars'
Let’s make a new version of this data by adding a column:
lper100km, consumption in liters per 100 km. This could
make our data friendlier to folks outside the United States.
<- mtcars mtcars_metric $lper100km <- 235.215 / mtcars$mpg mtcars_metric %>% pin_write(mtcars_metric, name = "mtcars", type = "json") board #> Creating new version '20120304T050607Z-19d36' #> Writing to pin 'mtcars'
Let’s check our board to ensure we have one pin named
"mtcars", with two versions:
%>% pin_list() board #>  "mtcars" %>% pin_versions("mtcars") board #> # A tibble: 2 × 3 #> version created hash #> <chr> <dttm> <chr> #> 1 20120304T050607Z-19d36 2012-03-03 22:06:07 19d36 #> 2 20120304T050607Z-c4fcd 2012-03-03 22:06:07 c4fcd
board_url() is consumed over the web, it
doesn’t have access to a file system the way, for example, a
board_folder() has; we can work around this by creating a
manifest file. When a
board_url() is set up by a consumer
for reading, the pins package uses this file to discover the pins and
their versions. The manifest file is the key to
board_url()’s ability to discover pins as if it were a
After writing pins but before publishing, call
%>% write_board_manifest() board #> Manifest file written to root folder of board, as `_pins.yaml`
The maintenance of this manifest file is not automated; it is your responsibility as the board publisher to keep the manifest up to date.
Let’s confirm that there is a file called
::with_dir(board$path, fs::dir_ls()) withr#> _pins.yaml mtcars
We can inspect its contents to see each pin in the board, and each version of each pin:
mtcars: - mtcars/20120304T050607Z-19d36/ - mtcars/20120304T050607Z-c4fcd/
At this point, we would publish the folder containing the board as a
part of a web site. Let’s pretend that we have served the folder from
our fake website,
With an up-to-date manifest file, a
behave as a read-only version of a
board_url() using our fake URL:
board_url() function reads the manifest file to
discover the pins and versions:
%>% pin_list() web_board #>  "mtcars" <- web_board %>% pin_versions("mtcars") versions versions#> # A tibble: 2 × 3 #> version created hash #> <chr> <dttm> <chr> #> 1 20120304T050607Z-19d36 2012-03-03 22:06:07 19d36 #> 2 20120304T050607Z-c4fcd 2012-03-03 22:06:07 c4fcd
We can read the most-recent version of the
%>% pin_read("mtcars") %>% head() web_board #> mpg cyl disp hp drat wt qsec vs am gear carb #> 1 21.0 6 160 110 3.90 2.620 16.46 0 1 4 4 #> 2 21.0 6 160 110 3.90 2.875 17.02 0 1 4 4 #> 3 22.8 4 108 93 3.85 2.320 18.61 1 1 4 1 #> 4 21.4 6 258 110 3.08 3.215 19.44 1 0 3 1 #> 5 18.7 8 360 175 3.15 3.440 17.02 0 0 3 2 #> 6 18.1 6 225 105 2.76 3.460 20.22 1 0 3 1
We can also read the first version:
%>% pin_read("mtcars", version = versions$version[]) %>% head() web_board #> mpg cyl disp hp drat wt qsec vs am gear carb lper100km #> 1 21.0 6 160 110 3.90 2.620 16.46 0 1 4 4 11.2007 #> 2 21.0 6 160 110 3.90 2.875 17.02 0 1 4 4 11.2007 #> 3 22.8 4 108 93 3.85 2.320 18.61 1 1 4 1 10.3164 #> 4 21.4 6 258 110 3.08 3.215 19.44 1 0 3 1 10.9914 #> 5 18.7 8 360 175 3.15 3.440 17.02 0 0 3 2 12.5783 #> 6 18.1 6 225 105 2.76 3.460 20.22 1 0 3 1 12.9953
The goal of this section is to illustrate ways to publish a board as a part of a website.
Pins offers another way for package developers to share data associated with an R package. Publishing a package dataset as a pin can extend your data’s “audience” to those who have not installed the package.
any files you save in the directory
pkgdown/assets/ will be
copied to the website’s root directory when
pkgdown::build_site() is run.
Packages book suggests using a folder called
data-raw for working with datasets; this can be adapted to
use pins. You would start with
a file in your
/data-raw directory, wrangle and clean your
datasets in the same way as if you were going to use
usethis::use_data(). To offer such datasets on a web-based
board instead of as a built-in package dataset, in your
/data-raw file you would:
board_folder(here::here("pkgdown/assets/pins-board"))(you might use a different name than
Now when you build your pkgdown site and serve it (perhaps via GitHub
Pages at a URL like
https://user-name.github.io/repo-name/), your datasets are
available as pins.
The R Packages book offers this observation on CRAN and package data:
Generally, package data should be smaller than a megabyte - if it’s larger you’ll need to argue for an exemption.
Publishing a board on your pkgdown site provides a way to offer datasets too large for CRAN or extended versions of your data. A consumer can read your pins by setting up a board like:
S3 buckets can be made available to different users using permissions;
buckets can even be made publicly accessible. Publishing data as a pin
in an S3 bucket can allow your collaborators to read without dealing
with the authentication required by
To offer datasets as a pin on S3 via
board_s3("your-existing-bucket")(set the bucket’s permissions to give appropriate people access).
S3 buckets typically have a URL like
For a person who has access to your bucket, they can read your pins by
setting up a board like: