In rstudio/pins: Pin, Discover, and Share Resources

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = rlang::is_installed("filelock")
)

pins 1.0.0 introduced a completely new API and the old legacy API was deprecated in pins 1.4.0, so now is a good time to switch to the new interface. This vignette shows a couple of examples of updating legacy code to the modern API, then provides a full set of equivalences between the legacy and modern function names.

library(pins)

Examples

A simple example of the legacy API looks something like this:

# Legacy API
board_register_local("vignette", tempfile())

pin(head(mtcars), "mtcars", board = "vignette")
pin_get("mtcars", board = "vignette")

To convert to the modern API you need to make two major changes:

Instead of registering a named board, you create an explicit board object.
You use pin_read() and pin_write() instead of pin_get() and pin().

# Modern API
board <- board_local()

pin_write(board, head(mtcars), "mtcars")
pin_read(board, "mtcars")

Since the board object is always the first argument, you might also want to use the pipe:

Sys.sleep(1)

# Modern API
board <- board_local()

board %>% pin_write(head(mtcars), "mtcars")
board %>% pin_read("mtcars")

Pinning files

Another way to use pin() is with a path to a file:

# Legacy API
path <- tempfile()
writeLines(letters, path)

pin(path, "alphabet", board = "vignette")
pin_get("alphabet", board = "vignette")

pins 1.0.0 clearly separates the two cases of pin an object and pinning a file, so here instead of pin_write() and pin_read() you need to pin_upload() and pin_download():

# Modern API
board %>% pin_upload(path, "alphabet")
board %>% pin_download("alphabet")

Pinning a url

Finally, you can pin() a url to automatically re-download it when it changes:

# Legacy API
base <- "https://raw.githubusercontent.com/rstudio/pins-r/main/tests/testthat/"

(pin(paste0(base, "pin-files/first.txt"), board = "vignette"))

This now needs to be made explicit with the new board_url(), and since this returns a path, not a file, you need to use pin_download():

# Modern API
board_github <- board_url(c(
  raw = paste0(base, "pin-files/first.txt")
))
board_github %>% pin_download("raw")

Implicit board

It's also possible to use pin() and pin_get() without an explicit board argument, in which case it automatically uses a local board:

# Legacy API
pin(data.frame(x = 1:3), "test-data")
pin_get("test-data")

To convert this code, you need to create an explicit board_local():

# Modern API
board <- board_local()

board %>% pin_write(data.frame(x = 1:3), "test-data")
board %>% pin_read("test-data")

Equivalents

Board functions

| Legacy API | Modern API | |------------------------------|---------------------------------------------------------| | board_register_azure() | board_azure() | | board_register_datatxt() | Not currently implemented | | board_register_dospace() | Not currently implemented | | board_register_gcloud() | board_gcs() | | board_register_github() | Use board_folder() together with board_url() | | board_register_local() | board_local() | | board_register_kaggle() | board_kaggle_dataset() / board_kaggle_competition() | | board_register_rsconnect() | board_connect() | | board_register_s3() | board_s3() | | pin() with a URL | board_url() |

Future releases will add support for additional boards based on user feedback.

Pin functions

| Legacy API | Modern API | |------------------|---------------------------------------------------| | board_browse() | pin_browse() | | pin() | pin_write() / pin_upload() | | pin_get() | pin_read() / pin_download() | | pin_find() | pin_search() | | pin_info() | pin_meta() | | pin_reactive() | pin_reactive_read() / pin_reactive_download() | | pin_remove() | pin_delete() |