Upgrading to pins 1.0.0

The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

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())
#> 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'`
#> ! 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    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] "/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():

# Modern API
board %>% pin_upload(path, "alphabet")
#> Replacing version '20241007T030546Z-ee580' with '20241007T153436Z-ee580'
board %>% pin_download("alphabet")
#> [1] "~/Library/Application Support/pins/alphabet/20241007T153436Z-ee580/file18498213615e2"

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] "/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():

# Modern API
board_github <- board_url(c(
  raw = paste0(base, "pin-files/first.txt")
))
board_github %>% pin_download("raw")
#> [1] "~/Library/Caches/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'`
#> ! The hash of pin "test-data" has not changed.
#> • Your pin will not be stored.
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()`

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.