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.
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    1To convert to the modern API you need to make two major changes:
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'`
#> ! The hash of pin "mtcars" has not changed.
#> • Your pin will not be stored.
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    1Since 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    1Another 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] "/var/folders/hv/hzsmmyk9393_m7q3nscx1slc0000gn/T/RtmpzMQjFB/file184982d4d3885/alphabet/file18498213615e2"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():
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] "/var/folders/hv/hzsmmyk9393_m7q3nscx1slc0000gn/T/RtmpzMQjFB/file184982d4d3885/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():
It’s also possible to use pin() and
pin_get() without an explicit board argument, in which case
it automatically uses a local board:
To convert this code, you need to create an explicit
board_local():
| 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 withboard_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.
| 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() |