pins 1.0.0 introduced a completely new API. While the legacy API will continue to be supported for some time, it will not gain any new features, so it’s good to plan 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)
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")
#> 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:
pin_read()
and pin_write()
instead
of pin_get()
and pin()
.# Modern API
<- board_local()
board
pin_write(board, head(mtcars), "mtcars")
#> Guessing `type = 'rds'`
#> Replacing version '20220822T205938Z-209d4' with '20220822T210529Z-209d4'
#> 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_local()
board
%>% pin_write(head(mtcars), "mtcars")
board #> Guessing `type = 'rds'`
#> Replacing version '20220822T210529Z-209d4' with '20220822T210529Z-209d4'
#> Writing to pin 'mtcars'
%>% pin_read("mtcars")
board #> 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
Another way to use pin()
is with a path to a file:
# Legacy API
<- tempfile()
path writeLines(letters, path)
pin(path, "alphabet", board = "vignette")
pin_get("alphabet", board = "vignette")
#> [1] "/var/folders/hv/hzsmmyk9393_m7q3nscx1slc0000gn/T/RtmpzUqxKB/file4a572be32502/alphabet/file4a5756a0a751"
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
%>% pin_upload(path, "alphabet")
board #> Replacing version '20220822T205938Z-ee580' with '20220822T210529Z-ee580'
%>% pin_download("alphabet")
board #> [1] "~/Library/Application Support/pins/alphabet/20220822T210529Z-ee580/file4a5756a0a751"
Finally, you can pin()
a url to automatically
re-download it when it changes:
# Legacy API
<- "https://raw.githubusercontent.com/rstudio/pins-r/master/tests/testthat/"
base
pin(paste0(base, "pin-files/first.txt"), board = "vignette"))
(#> [1] "/var/folders/hv/hzsmmyk9393_m7q3nscx1slc0000gn/T/RtmpzUqxKB/file4a572be32502/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_url(c(
board_github raw = paste0(base, "pin-files/first.txt")
))%>% pin_download("raw")
board_github #> [1] "~/Library/Caches/pins/url/26b8fc4e79ff84d4d95ece10d2bacb3c/first.txt"
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_local()
board
%>% pin_write(data.frame(x = 1:3), "test-data")
board #> Guessing `type = 'rds'`
#> Replacing version '20220822T205938Z-03a9b' with '20220822T210529Z-03a9b'
#> Writing to pin 'test-data'
%>% pin_read("test-data")
board #> x
#> 1 1
#> 2 2
#> 3 3
Legacy API | Modern API |
---|---|
board_register_azure() |
board_azure() |
board_register_datatxt() |
Not currently implemented |
board_register_dospace() |
Not currently implemented |
board_register_gcloud() |
Not currently implemented |
board_register_github() |
Not currently implemented |
board_register_local() |
board_local() |
board_register_kaggle() |
board_kaggle_dataset() /
board_kaggle_competition() |
board_register_rsconnect() |
board_rsconnect() |
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() |