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.

library(pins)

Examples

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

# Legacy API
board_register_local("vignette", tempfile())
#> Warning: `board_register_local()` was deprecated in pins 1.4.0.
#> ℹ Learn more at <https://pins.rstudio.com/articles/pins-update.html>
#> This warning is displayed once every 8 hours.
#> Call `lifecycle::last_lifecycle_warnings()` to see where this warning was
#> generated.

pin(head(mtcars), "mtcars", board = "vignette")
#> Warning: `pin()` was deprecated in pins 1.4.0.
#> ℹ Please use `pin_write()` instead.
#> This warning is displayed once every 8 hours.
#> Call `lifecycle::last_lifecycle_warnings()` to see where this warning was
#> generated.
pin_get("mtcars", board = "vignette")
#> Warning: `pin_get()` was deprecated in pins 1.4.0.
#> ℹ Please use `pin_read()` instead.
#> This warning is displayed once every 8 hours.
#> Call `lifecycle::last_lifecycle_warnings()` to see where this warning was
#> generated.
#>                    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

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")
#> Guessing `type = 'rds'`
#> Creating new version '20241106T055946Z-fe62f'
#> Writing to pin 'mtcars'
pin_read(board, "mtcars")
#>                    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

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")
#> Guessing `type = 'rds'`
#> ! The hash of pin "mtcars" has not changed.
#> • Your pin will not be stored.
board %>% pin_read("mtcars")
#>                    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

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")
#> [1] "/tmp/RtmpxSTUax/file157344ce2582/alphabet/file157351f92664"

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")
#> Creating new version '20241106T055947Z-ee580'
board %>% pin_download("alphabet")
#> [1] "~/.local/share/pins/alphabet/20241106T055947Z-ee580/file157351f92664"

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"))
#> [1] "/tmp/RtmpxSTUax/file157344ce2582/first/first.txt"

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")
#> [1] "~/.cache/pins/url/4bb0af0abae87c78f4a1b6fbe7e2642c/first.txt"

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")
#>   x
#> 1 1
#> 2 2
#> 3 3

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")
#> Guessing `type = 'rds'`
#> Creating new version '20241106T055947Z-66fa6'
#> Writing to pin 'test-data'
board %>% pin_read("test-data")
#>   x
#> 1 1
#> 2 2
#> 3 3

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

- Examples
- Equivalents