Upgrading to pins 1.0.0

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.

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:

# 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()`